API Overview

Overview

The Chartcastr Public API is a small, read-only REST surface for fetching your data sources and the latest pulse for each — the chart image, the short AI summary, and the long AI analysis. It’s the same data you see in your dashboard, available programmatically for embeds, internal tools, AI agents, or any integration project that needs structured access to your delivered insights.

For richer agent-style access (search, verify, deep links) use the MCP integrations — Claude, ChatGPT, Cursor, and Codex all connect via API key.

Base URL

https://public.api.chartcastr.com/v1

The same routes are also reachable at https://api.chartcastr.com/v1 (the production server uses both hosts).

Authentication

All requests require an API key passed in the X-API-Key header.

curl https://public.api.chartcastr.com/v1/sources \
  -H "X-API-Key: sk_live_..."

Generate keys from Settings → API Keys in your Chartcastr dashboard. Each key is scoped to a single account. Default expiry is 90 days.

API keys are shown once at creation time. Store them securely — if you lose a key you must revoke and regenerate.

Verify your key

There’s no dedicated /ping endpoint — instead, call GET /v1/sources to confirm a key works. Every successful response includes a meta.account object, so this single call doubles as both an access check and your first useful query. 200 means the key resolved; 401 means it’s missing, invalid, or expired.

GET /v1/sources — verify key & resolve account

Use this any time you want to confirm a key works before running a heavier integration flow. The response also tells you which account/email the key is bound to.Request

curl https://public.api.chartcastr.com/v1/sources \
  -H "X-API-Key: sk_live_..."

Success — 200

{
  "meta": {
    "account": {
      "id": "acc_2abc...",
      "email": "you@example.com"
    },
    "requestedAt": "2026-05-08T10:31:48.000Z"
  },
  "sources": [ /* ... */ ]
}

Failure — 401

{
  "success": false,
  "error": "Invalid or expired API key"
}

In CI/CD or onboarding flows, branch on the HTTP status: 200 → key works, 401 → prompt the user to regenerate, 429 → back off and retry.

Common failure modes

Symptom	Likely cause
`401 Invalid or expired API key`	Key revoked, expired, or never existed
`401 Authentication required`	`X-API-Key` header missing entirely
`429 Too Many Requests`	More than 60 calls in the last minute on this key
`200` but `meta.account.id` is unexpected	The key belongs to a different account than you thought

Response Shape

Every successful response includes a meta object so you can confirm which account the key resolved to:

{
  "meta": {
    "account": {
      "id": "acc_...",
      "email": "you@example.com"
    },
    "requestedAt": "2026-05-08T10:31:48.000Z"
  },
  "sources": [ ... ]
}

Errors

Status	Meaning
`401`	Missing or invalid `X-API-Key`
`403`	Key valid but lacks the required scope
`404`	Resource (source, pulse) not found for this account
`429`	Rate limit exceeded
`500`	Server error — retry with backoff

Error bodies follow the shape:

{
  "success": false,
  "error": "No pulse found for this source"
}

Rate Limits

Public API endpoints are rate limited to 60 requests per minute per API key. Each response includes the current window state in headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Requests left in the current window
`X-RateLimit-Reset`	Unix timestamp (seconds) when the window resets

OpenAPI Spec

The full machine-readable spec is served at:

GET https://public.api.chartcastr.com/v1/openapi.yaml

You can paste this directly into Postman, Insomnia, or any OpenAPI-aware tool to generate a typed client.

Getting Started

Sources

Destinations

Analysis

Stats

AI Tools

API

Streams

Admin

Overview

Base URL

Authentication

Verify your key

Common failure modes

Response Shape

Errors

Rate Limits

OpenAPI Spec

Endpoints

Sources

Pulses

​Overview

​Base URL

​Authentication

​Verify your key

​Common failure modes

​Response Shape

​Errors

​Rate Limits

​OpenAPI Spec

​Endpoints

Sources

Pulses

Overview

Base URL

Authentication

Verify your key

Common failure modes

Response Shape

Errors

Rate Limits

OpenAPI Spec

Endpoints