Building with the API? Open the developer docs

Finmagine API & MCP — free tier to test • Pro/Max for full access • REST + MCP

Open the Docs →

← API & Agent Integration Hub ← All Feature Guides

Published: July 29, 2026 | 9 min read | Developer Guide | API & Agent Integration Series

Multimedia Learning Hub

Master openapi.json and the API Reference page through a complete learning overview and interactive flashcards

What You Will Master

Both llms.txt and agent-recipes.json point here for a reason: openapi.json is the single source of truth every other Finmagine developer resource is generated from or defined against. This guide takes you inside the actual file, shows how a single operation is described end to end, and explains the discipline that keeps it from ever drifting out of sync with the code it documents.

What This Guide Covers:

Two Files, Two Jobs — openapi.json (machine contract) vs. the API Reference page (human-readable, generated)
What's Actually Inside openapi.json — info, servers, security, paths, tags, rate limits
Anatomy of a Single Operation — a real path definition, field by field
Why Tiers Can't Drift — tier classification is derived from actual handler source code, not hand-typed
openapi-compact.json — the lightweight sibling for routing
The API Reference Page — how it renders live, and never goes stale
Using openapi.json With Your Own Tools — codegen, OpenAPI-compatible clients, and agent frameworks

Who This Is For:

Developers integrating the API into their own codebase — generate a typed client instead of hand-writing request code
Agent framework builders — understand exactly what's machine-parseable versus what's narrative-only
Anyone who wants to trust that "the docs match the code" — this guide explains precisely why that's true here

Test Your Knowledge

Click any card to reveal the answer. Use the search box to find a specific topic.

Two Files, Two Jobs

Finmagine's developer surface has a machine-readable contract and a human-readable reference page, and it's worth being precise about which is which before going further — they're often conflated but they serve different readers.

File / Page	Format	Reader	Source of Truth?
`/openapi.json`	OpenAPI 3.1 JSON	Machines — codegen tools, OpenAPI-compatible clients, agent frameworks	Yes — everything else is generated from or defined against it
`/developer/api-reference.php`	Rendered HTML	Humans — developers reading in a browser	No — rendered live from openapi.json, never hand-authored

The API Reference page has no content of its own. Open developer/api-reference.php's source and you'll find almost no HTML for the actual endpoint listings — just a call to a renderer function that reads openapi.json at request time and builds the sidebar, tier chips, and parameter tables from it. If openapi.json is missing or fails to parse, the page shows an explicit "temporarily unavailable" notice rather than falling back to stale, hand-typed content.

THE CONTRACT

What's Actually Inside openapi.json

Finmagine's spec is standard OpenAPI 3.1 — any tool that already knows how to read an OpenAPI document can read this one without special handling. Here's the top-level shape:

{
  "openapi": "3.1.0",
  "info": {
    "title": "Finmagine Market Intelligence API",
    "version": "1.0.0",
    "description": "... 86 operations: 60 India + 26 US ..."
  },
  "servers": [{ "url": "https://finmagine.com/api/v1" }],
  "security": [
    { "apiKeyHeader": [] },
    { "bearerAuth": [] },
    { "apiKeyQuery": [] }
  ],
  "tags": [ "Core", "Company Intel", "Market Intel", "AI Content", "Feeds", "US Markets" ],
  "x-rate-limits": {
    "free":    { "per_day": 50,   "per_hour": 10   },
    "api_pro": { "per_day": 1000, "per_hour": 200  },
    "api_max": { "per_day": 5000, "per_hour": 1000 }
  },
  "x-mcp-endpoint": "https://finmagine.com/api/mcp.php",
  "x-mcp-only-tools": ["screen_natural_language"],
  "paths": { "/* 86 operations */" }
}

Three things worth noticing:

Three auth methods, one identity. apiKeyHeader (X-Api-Key), bearerAuth (Authorization: Bearer), and apiKeyQuery (?apiKey=) are all listed as valid — any one authenticates the same key, useful because some MCP clients only support Bearer auth while REST tooling often prefers a header.
x-rate-limits is the machine-readable twin of the pricing guide. The exact numbers from Understanding API & MCP Pricing Tiers live here too — an agent doesn't need to scrape a pricing page to know its limits, it can read them directly from the spec it already loaded.
x-mcp-only-tools flags the one operation with no REST equivalent. screen_natural_language exists only as an MCP tool — there's no /screener/nl REST path, because natural-language parsing is inherently an LLM-in-the-loop operation.

Anatomy of a Single Operation

Here's a real, complete operation from the live spec — get_momentum, one of the technical-analysis tools:

"/company/momentum": {
  "get": {
    "operationId": "get_momentum",
    "summary": "Technical momentum signals for an NSE company",
    "tags": ["Company Intel"],
    "parameters": [
      { "name": "symbol", "required": true,
        "description": "NSE ticker symbol" }
    ],
    "x-anchor": "get-momentum",
    "x-tier": "free",
    "x-mcp-tool": "get_momentum",
    "x-response-fields": [
      ["rs_rating", "IBD-style 1-99 rating vs Nifty 500 universe"],
      ["stage_2", "Weinstein Stage 2 uptrend flag"]
    ]
  }
}

Field	What it's for
`operationId`	The stable identifier — also doubles as the MCP tool name whenever a REST/MCP pair exists
`x-tier`	Minimum tier required — `free`, `api_pro`, or `api_max` — the exact field the pricing guide explains in depth
`x-mcp-tool`	The corresponding MCP tool name, or `null` for REST-only operations like `/status`
`x-anchor`	A stable anchor ID used to deep-link from other pages straight to this operation's section on the API Reference page
`x-response-fields`	A curated (not exhaustive) list of the most important response fields and what they mean — enough for an agent to know what to look for without guessing from a raw JSON blob

Every field prefixed x- is a Finmagine-specific OpenAPI extension. That's the standard, spec-compliant way to add custom metadata to an OpenAPI document — any generic OpenAPI tool will simply ignore fields it doesn't recognise, while Finmagine's own renderer and generator scripts read them directly.

Why Tiers Can't Drift

The single most important design decision behind openapi.json isn't a field — it's how the x-tier value on every operation gets set. It is not hand-typed anywhere. The generator script that builds openapi.json regex-scans each REST handler file's actual source code, every time it runs, looking for the real function calls that enforce access:

// generate-openapi.php classifies tier by scanning for these
// calls in the actual handler source — never executes the code,
// just looks for the literal function-call text
requireProTier()
requireMaxTier()
canAccessCompany()
canAccessUsCompany()

If a handler calls requireMaxTier(), that operation is classified x-tier: api_max in the generated spec — automatically, from the code that actually enforces it, not from a person remembering to update a table somewhere.

This project has hit hardcoded-count drift before — repeatedly. The total operation count baked into openapi.json's own description string has drifted out of sync with reality across multiple earlier phases (65→70, then 70→73) specifically because it once lived as a literal number typed in a place nowhere near the code that actually determines it. The tier-scanning approach exists to make sure the same thing can never happen to per-operation tier gates — the fix was to compute the count fresh from routes.php every single generation run, not to hope future edits remember to update a hand-typed number.

The practical result: if you ever see a mismatch between what the API Reference page says a tier requires and what the live endpoint actually enforces, that's a bug to report — by construction, the spec should always match the code, because it's derived from the code, not from someone's memory of the code.

openapi-compact.json — the Lightweight Sibling

The full spec is comprehensive but sizeable — everything an agent needs for one specific call, plus a lot it doesn't. openapi-compact.json strips each of the 86 operations down to just what's needed for routing:

{
  "generated_from": "openapi.json",
  "mcp_endpoint": "https://finmagine.com/api/mcp.php",
  "operations": [
    { "operationId": "get_momentum", "path": "/company/momentum",
      "tier": "free", "required_params": ["symbol"] }
    // ... 85 more, one line each ...
  ]
}

Use the compact index for "which endpoint handles this?" logic; use the full spec once you already know. An agent doing lightweight intent routing across 86 operations shouldn't need to hold full parameter descriptions, response-field lists, and tags for all of them in context just to pick one — fetch the compact index first, then load only the full definition for the operation it actually decided to call.

The API Reference Page

The API Reference page is what most human developers actually read — a sidebar-navigated, market-tabbed (🇮🇳 India / 🇺🇸 US) HTML rendering of the exact same 86 operations, generated fresh from openapi.json on every request.

What it adds on top of the raw spec

Sidebar navigation grouped by tag, jump-linked via each operation's x-anchor
Colour-coded tier chips — green for Free, blue for Pro, purple for Max — so tier is visible at a glance without reading JSON
REST + MCP badges side by side on every operation that has both, so you can see the REST path and the MCP tool name for the same operation in one place
A market tab switcher that swaps the entire sidebar and body between India and US operations without a page reload

What it deliberately doesn't do

If openapi.json can't be read or fails to parse, the page shows an explicit "API reference temporarily unavailable" notice and points to the narrative docs instead — it never silently falls back to a cached or hand-typed copy that could go stale without anyone noticing.

The hero banner across every developer page reads live counts the same way. The "86 REST + 86 MCP" style figures you see in the developer section's header aren't typed constants either — they're computed by iterating openapi.json's paths and the MCP tool definitions on every render, the exact same "generate, don't hand-type" discipline applied one level up, at the navigation-chrome level.

Using openapi.json With Your Own Tools

Because the spec is standard OpenAPI 3.1 with no proprietary format, several practical paths open up beyond just reading the reference page:

Generate a typed client. Any OpenAPI codegen tool (openapi-generator, openapi-typescript, etc.) can point directly at https://finmagine.com/openapi.json and produce typed request/response models for your language of choice, without hand-transcribing 86 endpoint signatures.
Import into API clients. Tools like Postman or Insomnia that support "import from OpenAPI URL" will build a full request collection automatically, with the correct auth scheme, parameters, and tags already in place.
Feed it to an agent framework directly. Any framework capable of ingesting an OpenAPI URL as a tool source can point at the spec and get all 86 operations as callable tools — this is exactly the path llms.txt lists first, ahead of the human-readable docs.
Validate your own integration. Run the spec through any OpenAPI 3.1 validator to confirm your request shapes match what Finmagine actually expects, before making a single live call.

openapi.json documents behavior; it does not control it. It's generated from the live handler code, but changing openapi.json by hand would only change what the spec claims — not what the actual API does. The one-way relationship (code → spec, never spec → code) is what keeps the two from silently diverging in the first place.

What's Next

This closes out Wave 1 — Discovery & Orientation. With llms.txt (how agents find Finmagine), pricing tiers (what they're allowed to call), and openapi.json (the exact contract for every call), the next wave moves into hands-on tools:

The Interactive API Explorer — try any of the 86 operations live in the browser before writing integration code
The Agentic Workflow Explorer — run pre-built multi-tool recipes end to end, including the async Investment Committee and Research Preset workflows

See the API & Agent Integration hub for the full 12-guide roadmap.

Ready to Analyse Indian Stocks Like a Pro?

Finmagine gives you 30+ computed financial ratios, sector benchmarks, FII/DII flows, the Finmagine Score, and AI-powered analysis — all in one place.

Analyse a Stock → Create Free Account