--- title: Jaspers for developers description: The APIs Jaspers offers - the Hub read API with its OpenAPI spec, the Screener and Research MCP servers with OAuth 2.0 sign-in, the plugin SDK, and the agent discovery files. canonical: https://jsprai.com/developers last-updated: 2026-10-13 --- # Jaspers for developers Everything Jaspers exposes over HTTP, in one place. The machine-readable version of this page is the OpenAPI document at https://jsprai.com/openapi.json; the agent-oriented version, with the tool workflows, is https://jsprai.com/agents.md. ## The services | Service | Base | Auth | Describes itself at | | --- | --- | --- | --- | | Jaspers Hub API | `https://hub-api.jsprai.com/v1` | None for reads | [openapi.json](https://jsprai.com/openapi.json) | | Jaspers Screener MCP | `https://s.jsprai.com/mcp` | OAuth 2.0, scope `mcp` | [server card](https://jsprai.com/.well-known/mcp/server-card.json), [resource metadata](https://s.jsprai.com/.well-known/oauth-protected-resource/mcp) | | Jaspers Research MCP | `https://analyst-api.jsprai.com/mcp/open` | OAuth 2.0, scope `mcp` | [server card](https://jsprai.com/.well-known/mcp/research-server-card.json), [resource metadata](https://analyst-api.jsprai.com/.well-known/oauth-protected-resource/mcp/open) | The Hub API lists the plugins and skills published for Jaspers Terminal. The two MCP servers are Model Context Protocol endpoints over SEC data: the Screener finds US public companies by their numbers and reads a short list against criteria in words; the Research server searches and reads one company's filings and verifies every quote against sec.gov. Each is a subscription on a Jaspers account, with a preview period on new accounts, managed at https://account.jsprai.com/auth/account. ## Quickstart: the Hub API No key, no sign-up. JSON in and out, camelCase names, ISO 8601 times in UTC. ```sh # Search published plugins curl 'https://hub-api.jsprai.com/v1/items?q=treasury&kind=plugin' # One item, with every version curl https://hub-api.jsprai.com/v1/items/jaspers/yfinance # One version in full: manifest, analysis, file index, archive address curl https://hub-api.jsprai.com/v1/items/jaspers/yfinance/versions/1.0.2 # Jaspers' own plugins curl https://hub-api.jsprai.com/v1/publishers/jaspers # Liveness curl https://hub-api.jsprai.com/v1/health ``` `GET /items` takes `q` (search text, at most 200 characters), `kind` (`plugin` or `skill`), `tag`, `sort` (`stars`, `new`, `downloads`; ignored with `q`), and `page` (from 1), thirty items a page. `GET /items/{handle}/{name}/archive` is the `.tar.gz` Jaspers Terminal installs, with `X-Hub-Version`, `X-Hub-Sha256`, and `X-Hub-Reviewed` headers. Publishing and starring need a Jaspers Account token and happen from Jaspers Terminal's Settings. ## Quickstart: the MCP servers Add the server to any MCP client that speaks Streamable HTTP and OAuth 2.0, and sign in when it asks. For Claude Code: ```sh claude mcp add --transport http jaspers-screener https://s.jsprai.com/mcp ``` For a client configured by file: ```json { "mcpServers": { "jaspers-screener": { "type": "http", "url": "https://s.jsprai.com/mcp" } } } ``` Inside Jaspers Terminal, both servers connect on the sign-in with Jaspers, through the [Screener](https://github.com/JaspersAI/plugin-screener-mcp) and [Research](https://github.com/JaspersAI/plugin-research) plugins. The tool workflows, conventions, and limits are in [agents.md](https://jsprai.com/agents.md), and as ready-made skills: [jaspers-screener](https://jsprai.com/.well-known/agent-skills/jaspers-screener/SKILL.md), [jaspers-research](https://jsprai.com/.well-known/agent-skills/jaspers-research/SKILL.md). ## Authentication One authorization server, `https://account.jsprai.com`, signs in to both MCP servers. Its metadata (RFC 8414) is at https://account.jsprai.com/.well-known/oauth-authorization-server: authorization code grant with PKCE `S256`, refresh tokens, public clients, dynamic client registration at `/oauth/register`, and client ID metadata documents, so a client can identify itself by the URL of its own metadata. Request the token for the resource you will call (RFC 8707 `resource`): `https://s.jsprai.com/mcp` or `https://analyst-api.jsprai.com/mcp/open`. The one scope is `mcp`; what each tool may do follows the account's subscriptions. An unauthenticated request answers `401` with a `WWW-Authenticate: Bearer` challenge whose `resource_metadata` names the server's protected resource metadata (RFC 9728). An account is created on first sign-in. The step-by-step walkthrough for agents is https://jsprai.com/auth.md. There are no API keys to generate, and no sandbox: the preview period on a new account is the trial. ## Versioning and deprecation The Hub API is versioned in its path, `/v1`. Additive changes, a new field or a new route, arrive without a version change and never remove or rename what is there. A breaking change ships as a new path version; the old version keeps answering for at least 90 days after the new one appears, and during that period its responses carry `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers naming the dates. The MCP servers speak the protocol version negotiated at `initialize`, and their tool lists are what `tools/list` returns on the day; a tool that goes away is removed from the list rather than left answering errors. ## Errors and limits The Hub API answers every error as JSON, `{"error": {"message": "…"}}`, with `400` for a bad query, `404` for nothing there, `410` for a rejected or withdrawn version (the message carries the note), `429` for too many requests with `Retry-After` in seconds, `502` when a service it depends on did not answer, and `503` when the database did not. Reads are limited to 20 requests per second per client. The MCP servers answer MCP's own JSON-RPC errors inside a `200`, and `401` for a missing or invalid token. ## Building on Jaspers Terminal - [`@jaspers-ai/sdk`](https://www.npmjs.com/package/@jaspers-ai/sdk) on npm: `definePlugin`, `defineSource`, `defineView`, the view hooks, and the skills helpers. Docs: [Writing a plugin](https://github.com/JaspersAI/terminal/blob/main/docs/writing-a-plugin.md), [SDK reference](https://github.com/JaspersAI/terminal/blob/main/docs/sdk-reference.md), [Publishing a plugin](https://github.com/JaspersAI/terminal/blob/main/docs/publishing-a-plugin.md), [Skills](https://github.com/JaspersAI/terminal/blob/main/docs/skills.md). - Source: [JaspersAI/terminal](https://github.com/JaspersAI/terminal) (MIT) and the official plugins under [github.com/JaspersAI](https://github.com/JaspersAI). - Official skills for coding agents: `npx skills add JaspersAI/skills`, or the index at https://jsprai.com/.well-known/agent-skills/index.json. ## Trust and verification How to check that something claiming to be Jaspers is Jaspers: - Every discovery document on this site (the ARD catalog, the server cards, the skills index, this page) is served from `https://jsprai.com` over TLS; the catalog's `trustManifest.identity` is that origin. - Each skill in https://jsprai.com/.well-known/agent-skills/index.json carries the SHA-256 of its `SKILL.md`; verify the bytes before loading. The same skills are the public repository https://github.com/JaspersAI/skills. - Each MCP server publishes RFC 9728 protected resource metadata on its own host, naming `https://account.jsprai.com` as its only authorization server; tokens are ES256 JWTs verifiable against https://account.jsprai.com/.well-known/jwks.json. - Jaspers Terminal and the official plugins are public source under MIT at https://github.com/JaspersAI. ## Discovery files - [openapi.json](https://jsprai.com/openapi.json): this surface as OpenAPI 3.1 - [ard.json](https://jsprai.com/.well-known/ard.json): the Agentic Resource Discovery catalog - [api-catalog](https://jsprai.com/.well-known/api-catalog): RFC 9727 linkset - [llms.txt](https://jsprai.com/llms.txt) and [agents.md](https://jsprai.com/agents.md) - [auth.md](https://jsprai.com/auth.md): how an agent obtains credentials, step by step - [Agent Plugin](https://github.com/JaspersAI/skills): `plugin.json` and `mcp.json` bundle the skills and both MCP servers; `AGENTS.md` there is for coding agents - Status: https://hub-api.jsprai.com/v1/health, https://s.jsprai.com/health, https://analyst-api.jsprai.com/health, https://account.jsprai.com/health ## Support hub@jsprai.com. Bugs in Jaspers Terminal: https://github.com/JaspersAI/terminal/issues. See [contact](https://jsprai.com/contact).