> ## Documentation Index > Fetch the complete documentation index at: https://docs.spreadjam.com/llms.txt > Use this file to discover all available pages before exploring further. # Quickstart for agents > Connect Claude, ChatGPT, Claude Code, Cursor or any agent to Jam: sign in or get a key, add the MCP server, make your first five calls. Jam tracks how AI assistants answer the questions your buyers ask, and turns the gaps into a Plan of actions. Everything a customer does in the dashboard is available to an agent through the REST API at `https://api.spreadjam.com/v1` and the MCP server at `https://api.spreadjam.com/mcp`. Jam scans ChatGPT, Gemini, Perplexity, Google AI Mode, Google AI Overviews and Microsoft Copilot. ## 1. Get an API key > [tab] From an agent (agent connect) > > The agent starts a session. No key is needed for this call. > > ```bash theme={} > curl -sS -X POST https://api.spreadjam.com/v1/agent-connect \ > -H "Content-Type: application/json" \ > -d '{"domain": "acme.com", "agentName": "Claude Code"}' > ``` > > ```json theme={} > { > "connectUrl": "https://www.spreadjam.com/connect/ABCD234567", > "userCode": "K7M-Q2X", > "pollToken": "jcp_...", > "expiresAt": "2026-11-04T12:00:00.000Z", > "intervalSeconds": 5 > } > ``` > > `agentName` is optional (1 to 60 printable characters; without it the page says "Your agent"). `domain` is optional and must be a website hostname such as `acme.com`. `email` is optional too: the human's email, if you know it. Anything else is a `400 invalid_request` whose `details` names the field. > > Give the human the `connectUrl` and the `userCode` together, for example: "Open this link and check that it shows the code K7M-Q2X." The approval page shows the same code, the email they are signed in with and the workspace the key will belong to (they can switch to another of their workspaces there). They sign up or sign in, set up their site (the domain you sent is filled in), choose a plan, and approve. If they already use Jam, they only approve. After they approve, the page tells them to return to you while you finish connecting. > > Keep the `pollToken` secret, and poll every `intervalSeconds`: > > ```bash theme={} > curl -sS https://api.spreadjam.com/v1/agent-connect/$POLL_TOKEN > ``` > > | `status` | Meaning | > | - | - | > | `pending` | Not done yet. `stage` says what is left: `awaiting_signin`, `awaiting_review`, `awaiting_payment` (approved, the trial has not started) or `setting_up` (paid, the project is being created). Poll again. | > | `approved` | The response carries `apiKey` and `workspaceId`. This is the only time the key is shown: store it now. | > | `consumed` | The key was already handed out. Start a new session if it was lost. | > | `denied` | The human declined. | > | `expired` | Nobody approved within two hours. Start a new session. | > > Starting sessions is limited to 10 per IP address every 10 minutes. > > #### Set Jam up for them (recommended) > > You can do the setup yourself, so the human only reviews, pays and approves. Read the plans first (no key needed): > > ```bash theme={} > curl -sS https://api.spreadjam.com/v1/pricing > curl -sS "https://api.spreadjam.com/v1/pricing?promptCapacity=100&cadence=weekly&platforms=chatgpt,gemini,perplexity,google_ai_overview" > ``` > > The first lists prompt capacities (50 to 1,000 in steps of 50), scan cadences, platforms, work credits, the monthly price of every capacity and cadence, and the trial terms (14 days for a new account, card required). The second quotes one configuration. These are the prices the plan page shows. > > Then send the setup as `onboarding`: > > ```bash theme={} > curl -sS -X POST https://api.spreadjam.com/v1/agent-connect \ > -H "Content-Type: application/json" \ > -d '{ > "agentName": "Claude Code", > "email": "founder@acme.com", > "onboarding": { > "site": "acme.com", > "brandName": "Acme", > "description": "Acme is invoicing and time tracking software for agencies of 5 to 50 people that bill clients by the hour.", > "audience": [ > { "title": "Agency owners", "blurb": "Run a 5 to 50 person services agency" }, > { "title": "Operations leads", "blurb": "Own billing and time tracking at an agency" } > ], > "competitors": [ > { "name": "Harvest", "domain": "getharvest.com" }, > { "name": "FreshBooks", "domain": "freshbooks.com" } > ], > "prompts": [ > { "text": "best invoicing software for small agencies", "topic": "Agency invoicing", "persona": "buyer" }, > { "text": "Harvest vs FreshBooks for agency time billing", "topic": "Time billing", "persona": "competitor" }, > { "text": "how should a 20 person agency track billable hours", "topic": "Time billing", "audience": "Operations leads" } > ], > "locale": "us-en", > "plan": { > "promptCapacity": 100, > "cadence": "weekly", > "platforms": ["chatgpt", "gemini", "perplexity", "google_ai_overview"] > } > } > }' > ``` > > The answer adds `reviewUrl` (the same link as `connectUrl`), the quoted `plan` and the prompt count: > > ```json theme={} > { > "connectUrl": "https://www.spreadjam.com/connect/ABCD234567", > "reviewUrl": "https://www.spreadjam.com/connect/ABCD234567", > "userCode": "K7M-Q2X", > "pollToken": "jcp_...", > "expiresAt": "2026-11-04T12:00:00.000Z", > "intervalSeconds": 5, > "plan": { > "configuration": { "promptCapacity": 100, "cadence": "weekly", "platforms": ["chatgpt", "gemini", "perplexity", "google_ai_overview"], "workCredits": 2000 }, > "currency": "usd", > "monthlyCents": 18600, > "monthlyUsd": 186 > }, > "prompts": { "count": 3, "suggestedByJam": false } > } > ``` > > Every field is optional except the site (`onboarding.site`, or `domain`). The rules are the ones onboarding applies: `brandName` and `description` together (description 20 to 2,000 characters), 1 to 5 audiences, up to 25 competitors (never the site itself), prompts of 8 to 300 characters with no duplicates, at most 15 topics and at most `plan.promptCapacity` prompts. A prompt without `topic` goes under "General"; `persona` is one of `discoverer` (default), `buyer`, `evaluator`, `competitor`, `branded`; `audience` names one of your audience titles. Leave out `prompts` and Jam suggests them from the site, and the human reviews them before the trial. Anything that breaks a rule is a `400 invalid_request` whose `details` names the field, for example `onboarding.prompts.2`. > > The link then opens one review page instead of the onboarding steps: the code, the site, the brand, audiences, competitors, prompts, the plan with its price (the human can change it), what the key can do, and one button, "Approve Claude Code and start trial", which opens checkout. Tell the human what to expect, for example: "Open this link, check the code K7M-Q2X, review the setup and press Approve. Checkout asks for a card; the trial is free for 14 days." While you poll, `stage` tells you what is left; the key arrives on the first poll after the trial has started and the project exists, with no second approval. If the human already has a Jam workspace with an active plan or a finished project, they approve for that workspace and your setup is not applied. A workspace left unpaid from an earlier attempt still gets your setup. While the human has approved but not paid, the poll returns `reason`, `resumeUrl` and `humanMessage`: pass the message and link on so they can finish checkout; the session waits 24 hours after approval. > > > [!TIP] > > > > **Python: set a `User-Agent` header.** The API sits behind Cloudflare, which blocks the default `Python-urllib/3.x` user agent with `403` ("error code: 1010"). Send your own, for example `urllib.request.Request(url, headers={"User-Agent": "my-agent/1.0"})`, and do the same with any HTTP client whose requests come back `403` with that body. > [tab] From the dashboard > > 1. Open Jam and go to **Settings**, then **Developer**. > 2. Click **Create API key** and give it a name. > 3. Copy the key. It is shown once. Keys look like `sk_` followed by 64 hex characters. A key reaches its workspace's real data; there are no test keys. It can read everything in the workspace and make the changes its creator can make in the dashboard, including work that spends credits; it acts with its creator's role, so a member's key cannot do owner-only things such as managing billing. Revoke a key in **Settings**, **Developer** (a key can also revoke itself with `DELETE /v1/api-keys/{keyId}`). ## 2. Connect over MCP The MCP server exposes every API route as a tool, named by its operation id (`get_me`, `list_prompts`, `list_actions`, ...). ### Claude.ai, Claude Desktop, ChatGPT: sign in, no key Clients that support OAuth connectors sign in to Jam directly, so you skip step 1. * **Claude.ai or Claude Desktop:** **Settings**, **Connectors**, **Add custom connector**, then enter `https://api.spreadjam.com/mcp`. * **ChatGPT:** add a connector (developer mode) with the URL `https://api.spreadjam.com/mcp` and OAuth authentication. The client opens a Jam page in your browser. Sign in (or sign up and choose a plan), check the workspace and where you will be sent back to, and approve. The connection appears in **Settings**, **Developer** as a key named after the client, for example "Claude (connector)"; revoke it there to disconnect. ### With an API key Other clients send the key from step 1. ```bash Claude Code theme={} claude mcp add --transport http jam https://api.spreadjam.com/mcp \ --header "Authorization: Bearer $JAM_API_KEY" ``` ```json Cursor (.cursor/mcp.json) theme={} { "mcpServers": { "jam": { "url": "https://api.spreadjam.com/mcp", "headers": { "Authorization": "Bearer sk_..." } } } } ``` Tools are annotated, so your client can auto-approve the safe ones and ask before the rest: * Reads are `readOnlyHint: true`. * Tools that spend credits, publish to your site or repository, or delete something are `destructiveHint: true`. A tool that spends credits says what it costs at the start of its description (for example `create_research_request`: "Costs 500 credits (the first research run is free)."). * Tools that are safe to repeat are `idempotentHint: true`. Tools a key can never use (creating API keys, the key-less agent-connect calls) are not listed. To work on a project other than your newest one, pass `projectId` (an id from `list_projects`) to any project tool, or send `X-Jam-Project: ` with the MCP connection. The argument wins for that one call. Prefer plain HTTP? Use the [OpenAPI spec](https://api.spreadjam.com/openapi.json) and send `Authorization: Bearer $JAM_API_KEY` on every request. ## 3. Your first five calls ```bash theme={} export JAM=https://api.spreadjam.com/v1 auth=(-H "Authorization: Bearer $JAM_API_KEY") curl -sS "${auth[@]}" $JAM/me # which workspace this key is for curl -sS "${auth[@]}" $JAM/analytics/overview # visibility, mentions, citations curl -sS "${auth[@]}" "$JAM/prompts?limit=20" # what is tracked, one page curl -sS "${auth[@]}" $JAM/actions # the Plan: what to do next curl -sS "${auth[@]}" $JAM/credits # credits left and when they reset ``` Over MCP these are `get_me`, `get_analytics_overview`, `list_prompts` (with `limit: 20`), `list_actions` and `get_credits`. Always send `limit` to `/v1/prompts`: without it the response also carries the older `tracked` and `archived` lists next to the first page, which is a few hundred KB on a large project. The first `analytics` read of a project can take several seconds while Jam builds its numbers; later reads are fast until a new scan lands. ## Next * [Concepts](https://docs.spreadjam.com/agents/concepts.md): projects, prompts, scans, answers, the Plan, research and credits. * [How to operate Jam](https://docs.spreadjam.com/agents/operating-guide.md): a page to paste into your agent's context. * [Errors and limits](https://docs.spreadjam.com/api-reference/errors.md): error codes, rate limits and idempotency. * Help: email [jia@spreadjam.com](mailto:jia@spreadjam.com) or [mal@spreadjam.com](mailto:mal@spreadjam.com), and quote the `requestId` from the error. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.