API Documentation

Complete endpoint reference. All examples are copy/paste ready.

OpenAPI JSON Open Portal

LLM-friendly summary

- GET /healthz
  purpose: Liveness check for service process availability.
  auth: None
- GET /readyz
  purpose: Readiness check for db/redis/queue dependencies.
  auth: None
- GET /v1/news/search
  purpose: Main ranked feed endpoint (supports pagination + language filters).
  auth: Bearer API key
- GET /v1/briefing
  purpose: Generates briefing payload or digest for end-user and agent usage.
  auth: Bearer API key
- GET /v1/briefing/agent
  purpose: Agent-optimized contract payload for automated workflows.
  auth: Bearer API key
- POST /v1/profile/sync
  purpose: Triggers profile sync from manual/x-browser/x-api modes.
  auth: Bearer API key
- GET /v1/sources
  purpose: Lists source registry used in ranking and ingestion.
  auth: Bearer API key
- POST /v1/oauth/x/start
  purpose: Starts X OAuth PKCE flow for self-serve onboarding.
  auth: None
- GET /openapi.json
  purpose: Machine-readable OpenAPI schema reference.
  auth: None
GET /healthz

Liveness check for service process availability.

Auth
None
Response
success:boolean data.status:string
curl -s https://newsintelapi.com/healthz
GET /readyz

Readiness check for db/redis/queue dependencies.

Auth
None
Response
success:boolean data.ready:boolean
curl -s https://newsintelapi.com/readyz
GET /v1/news/search

Main ranked feed endpoint (supports pagination + language filters).

Auth
Bearer API key
Query
limit:number page:number lang:string csv country:string topics:string csv
Response
success:boolean count:number quality:object items:NewsItem[]
curl -s -H "Authorization: Bearer <API_KEY>" \
  "https://newsintelapi.com/v1/news/search?limit=24&page=1&lang=pt,en"
GET /v1/briefing

Generates briefing payload or digest for end-user and agent usage.

Auth
Bearer API key
Query
format: json|digest for_agent:1 country topics bias since_hours limit
Response
success:boolean status:string sections:object digest_markdown?:string
curl -s -H "Authorization: Bearer <API_KEY>" \
  "https://newsintelapi.com/v1/briefing?format=digest&country=BR"
GET /v1/briefing/agent

Agent-optimized contract payload for automated workflows.

Auth
Bearer API key
Response
success:boolean agent_contract:object sections:object
curl -s -H "Authorization: Bearer <API_KEY>" "https://newsintelapi.com/v1/briefing/agent"
POST /v1/profile/sync

Triggers profile sync from manual/x-browser/x-api modes.

Auth
Bearer API key
Body
mode: manual|x-browser|x-api free_text?: string x_username?: string
Response
success:boolean sync_job_id:string status:string
curl -s -X POST -H "Authorization: Bearer <API_KEY>" -H "content-type: application/json" \
  -d '{"mode":"manual","free_text":"crypto macro AI"}' https://newsintelapi.com/v1/profile/sync
GET /v1/sources

Lists source registry used in ranking and ingestion.

Auth
Bearer API key
Response
success:boolean count:number sources:Source[]
curl -s -H "Authorization: Bearer <API_KEY>" https://newsintelapi.com/v1/sources
POST /v1/oauth/x/start

Starts X OAuth PKCE flow for self-serve onboarding.

Auth
None
Body
redirect_uri:string workspace_id?:string
Response
success:boolean authorize_url:string
curl -s -X POST -H "content-type: application/json" \
  -d '{"redirect_uri":"https://newsintelapi.com/oauth/x/callback"}' https://newsintelapi.com/oauth/x/start
GET /openapi.json

Machine-readable OpenAPI schema reference.

Auth
None
Response
openapi:string paths:object components:object
curl -s https://newsintelapi.com/openapi.json