API Reference

Base URL: https://api.orbis.builder
Authentication: X-API-Key: ob_live_...

POST/api/v1/search

Search news articles by keyword, semantic similarity, or both.

Request

curl -X POST https://api.orbis.builder/api/v1/search \
  -H "X-API-Key: ob_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "klimapolitik",
    "mode": "keyword",
    "country": "dk",
    "limit": 10,
    "from_date": "2026-08-01"
  }'

Response

{
  "results": [
    {
      "article_id": 89234012,
      "title": "Ny klimaaftale moder modstand i Folketinget",
      "source": "dr.dk",
      "url": "https://dr.dk/nyheder/...",
      "published_at": "2026-08-09T16:20:00Z",
      "availability": "free",
      "time_on_frontpage_minutes": 145,
      "thread_id": 7823,
      "sites_covering": 8,
      "score": null
    }
  ],
  "total": 1847,
  "limit": 10,
  "offset": 0,
  "has_more": true,
  "mode": "keyword"
}

POST/api/v1/agents

Create a keyword monitoring agent that collects matching articles.

Request

curl -X POST https://api.orbis.builder/api/v1/agents \
  -H "X-API-Key: ob_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Danish Climate Policy",
    "keywords": [
      {"value": "klimapolitik", "strict": false},
      {"value": "Danske Bank", "strict": true}
    ],
    "country": "dk"
  }'

Response

{
  "agent_id": 4521,
  "name": "Danish Climate Policy",
  "status": "active",
  "country": "dk",
  "keywords": [
    {"value": "klimapolitik", "strict": false},
    {"value": "Danske Bank", "strict": true}
  ],
  "article_count": 0,
  "created_at": "2026-08-09T14:30:00Z"
}

GET/api/v1/agents/{agent_id}/articles

Fetch articles collected by a monitoring agent.

Request

curl https://api.orbis.builder/api/v1/agents/4521/articles?limit=5&since=2026-08-08 \
  -H "X-API-Key: ob_live_..."

Response

{
  "agent_id": 4521,
  "articles": [
    {
      "article_id": 89234012,
      "title": "Ny klimaaftale moder modstand",
      "source": "dr.dk",
      "url": "https://dr.dk/nyheder/...",
      "published_at": "2026-08-09T16:20:00Z",
      "availability": "free",
      "thread_id": 7823,
      "sites_covering": 8
    }
  ],
  "total": 342,
  "limit": 5,
  "offset": 0,
  "has_more": true
}

GET/api/v1/articles/{article_id}/thread

Get all coverage of the same story across different sources.

Request

curl https://api.orbis.builder/api/v1/articles/89234012/thread?country=dk \
  -H "X-API-Key: ob_live_..."

Response

{
  "thread_id": 7823,
  "headline": "Ny klimaaftale moder modstand i Folketinget",
  "first_seen": "2026-08-09T08:15:00Z",
  "total_sites": 8,
  "total_articles": 14,
  "total_minutes": 2340,
  "articles": [...],
  "sites": [
    {"site_id": 42, "site_name": "dr.dk", "article_count": 2, "on_frontpage": true}
  ]
}

GET/api/v1/timeline

Track how a topic has been covered over time.

Request

curl "https://api.orbis.builder/api/v1/timeline?query=Danske+Bank&country=dk&granularity=day" \
  -H "X-API-Key: ob_live_..."

Response

{
  "query": "Danske Bank",
  "country": "dk",
  "from_date": "2026-07-09",
  "to_date": "2026-08-09",
  "granularity": "day",
  "buckets": [
    {
      "date": "2026-08-09",
      "article_count": 7,
      "site_count": 4,
      "top_articles": [...]
    }
  ],
  "total_articles": 89,
  "total_sites": 12
}

GET/api/v1/sites

List available news sites and their current activity.

Request

curl https://api.orbis.builder/api/v1/sites?country=dk \
  -H "X-API-Key: ob_live_..."

Response

{
  "sites": [
    {
      "site_id": 42,
      "site_name": "dr.dk",
      "site_url": "https://dr.dk",
      "country": "dk",
      "type": "news",
      "story_count_24h": 87,
      "accessible": true
    }
  ],
  "total": 45,
  "entitled_countries": ["dk"],
  "entitled_site_types": ["news"]
}

GET/api/v1/usage

Check current API usage and remaining quota.

Request

curl https://api.orbis.builder/api/v1/usage \
  -H "X-API-Key: ob_live_..."

Response

{
  "key_id": "ob_live_abc12345",
  "period": "2026-08",
  "requests": {
    "total": 2847,
    "quota": 5000,
    "remaining": 2153,
    "by_category": {"search": 1200, "agents": 847, "articles": 600, "platform": 200}
  },
  "agents": {"active": 3, "paused": 1, "limit": 10},
  "entitlements": {"countries": ["dk"], "site_types": ["news"], "plan": "pro"}
}

Error Format

All errors follow this structure:

Error response

{
  "error": "quota_exceeded",
  "status_code": 429,
  "message": "Monthly request quota exceeded (5000/5000)",
  "hint": "Upgrade your plan at https://orbis.builder/billing"
}