AI agents & API
Agent API
A plain REST API over the same tools: POST JSON to /api/agent/<tool>, authenticate with an agent API key, and get JSON back. Described by an OpenAPI 3.1 spec at /openapi.json.
Endpoint
Every tool is a single POST with a JSON body and a JSON reply. No SDK needed; the same tools are also exposed over MCP and wrapped by the CLI.
POST /api/agent/<tool>
curl -X POST https://www.tryspook.com/api/agent/analyze_domain \
-H "Content-Type: application/json" \
-d '{"domain":"example.com"}'The reply wraps the tool's result:
200 · application/json
{ "tool": "list_sites", "result": [ … ] }GET /api/agent lists every tool with its input schema, and GET /api/agent/<tool>returns one tool's schema, so an agent can discover the surface without reading these docs.
Authentication
Account tools need an agent API key. Generate one in Settings → Agent API and send it as a bearer token:
bash
curl -X POST https://www.tryspook.com/api/agent/list_sites \
-H "Authorization: Bearer spook_agent_xxxxxxxx"Keep the key server-side
The key acts as you: it can create sites, spend article credits and publish. Never ship it in a browser bundle.
Core tools
The product itself: sites, opportunities, article generation and publishing, autopilot. analyze_domain is free and needs no key.
| Tool | What it does | Auth |
|---|---|---|
| analyze_domain | Free, no-signup SEO snapshot for any domain: the queries it already ranks on page 1-2 for (its quick-win opportunities), with search volume and estimated traffic. Great first look before signing up. | Free |
| list_sites | List the Spook sites on the account this API key belongs to, with each site's id, domain, autopilot state, and publishing setup. | API key |
| get_site | Get one site's details and status by its id. | API key |
| list_opportunities | The winnable search queries Spook has found for a site (scored, ranked). No cost. Pass questionsOnly to get only question-shaped queries. | API key |
| list_articles | Recent articles for a site with their status (draft/review/published) and generation status. | API key |
| generate_article | Generate a new SEO article draft for a site targeting a search query. Returns an articleId immediately; generation runs in the background - poll get_article/list_articles, or pass callbackUrl to be notified. Idempotent per query (a repeat returns the existing article). Requires an active subscription. | API key |
| get_article | Fetch one article by id: full markdown body, meta, FAQs, SEO score, status, and published URL. Use to review a draft before publishing. | API key |
| get_site_metrics | Read a site's performance: daily Search Console clicks/impressions trend plus cached SEO metrics (domain rating, organic traffic estimate, top keywords). No cost. Use to check whether Spook is working. | API key |
| create_site | Add a new site to the account. Language/market is auto-detected from the homepage. Requires an available paid site slot (use create_checkout first if none). Returns the new siteId. | API key |
| update_publishing | Configure where a site publishes. Set publishIntegration to 'nextjs' for a credential-free Spook-hosted blog (returns a blog API key), or 'webhook' with publishWebhookUrl. publishMode 'draft' or 'live'. | API key |
| create_checkout | Get a Stripe Checkout URL to add the first paid site to the account. Return the URL to the user to approve payment. Needed before create_site if the account has no available slot. | API key |
| publish_article | Publish a generated article to the site's connected CMS. Enforces Spook's SEO-score floor - a draft below it is refused (returns published:false with a reason). | API key |
| set_autopilot | Turn a site's autopilot on or off. When on, Spook plans, writes, and publishes articles automatically. | API key |
Free AI tools
The 21 AI-backed writers from the free tools suite (blog outlines, content briefs, rewrites, meta descriptions and more) run over the same endpoint. No key required; per-IP and daily caps apply.
| Tool | What it does |
|---|---|
| blog-keyword-generator | Blog Keyword Generator: Generate SEO keyword ideas for a topic, with search intent and difficulty. (free, AI-generated, rate-limited). |
| content-brief-generator | Content Brief Generator: Create a detailed SEO content brief for a target keyword. (free, AI-generated, rate-limited). |
| blog-outline-generator | Blog Outline Generator: Produce a structured, SEO-friendly blog post outline. (free, AI-generated, rate-limited). |
| content-idea-generator | Content Idea Generator: Generate content ideas with formats and angles for a niche. (free, AI-generated, rate-limited). |
| seo-title-generator | SEO Title Generator: Write catchy, SEO-friendly title tags for a topic. (free, AI-generated, rate-limited). |
| meta-description-generator | Meta Description Generator: Write SEO meta descriptions that maximize click-through rate. (free, AI-generated, rate-limited). |
| headline-generator | Headline Generator: Generate catchy, click-worthy headlines. (free, AI-generated, rate-limited). |
| subject-line-generator | Email Subject Line Generator: Write high-converting email subject lines. (free, AI-generated, rate-limited). |
| cta-generator | CTA Generator: Write effective call-to-action phrases. (free, AI-generated, rate-limited). |
| ad-copy-generator | Ad Copy Generator: Generate ad headlines and descriptions. (free, AI-generated, rate-limited). |
| social-post-generator | Social Media Post Generator: Write platform-specific social media posts. (free, AI-generated, rate-limited). |
| article-summarizer | AI Article Summarizer: Condense an article into a TL;DR, key points, and summary. (free, AI-generated, rate-limited). |
| article-rewriter | AI Article Rewriter: Rephrase text to be clearer, unique, and engaging. (free, AI-generated, rate-limited). |
| grammar-checker | AI Grammar Checker: Fix grammar, spelling, and punctuation, and list the corrections. (free, AI-generated, rate-limited). |
| faq-generator | FAQ Generator: Generate a set of frequently asked questions and answers for a topic. (free, AI-generated, rate-limited). |
| product-description-generator | Product Description Generator: Write persuasive product descriptions. (free, AI-generated, rate-limited). |
| business-name-generator | Business Name Generator: Generate brandable business name ideas. (free, AI-generated, rate-limited). |
| youtube-title-generator | YouTube Title & Description Generator: Write a YouTube title, description, and tags for a video topic. (free, AI-generated, rate-limited). |
| paragraph-generator | Paragraph Generator: Expand a topic or sentence into a well-written paragraph. (free, AI-generated, rate-limited). |
| content-coverage-checker | Content Coverage Checker: List the terms and entities an article targeting a keyword is expected to cover. (free, AI-generated, rate-limited). |
| hashtag-generator | Hashtag Generator: Generate relevant hashtags for a topic and platform. (free, AI-generated, rate-limited). |
Free SEO tools
The 25 deterministic SEO utilities (meta tags, schema, robots.txt, SERP preview, readability, keyword density, …) live at POST /api/tools/<slug>, no auth. GET /api/tools lists them with their input schemas.
Errors
Errors are JSON with a human message and a stable code:
401 · application/json
{ "error": "Missing agent API key. Send Authorization: Bearer spook_agent_...", "code": "missing_api_key" }| Status | Code | Meaning |
|---|---|---|
| 400 | bad_request | The tool rejected the input (message says why). |
| 400 | invalid_json | The request body is not valid JSON. |
| 401 | missing_api_key | An account tool was called without a bearer token. |
| 401 | invalid_api_key | The key is unknown or revoked. |
| 402 | payment_required | The site's subscription or trial does not cover this action. |
| 404 | unknown_tool | No tool by that name - check GET /api/agent. |
| 404 | not_found | The site or article id does not exist, or is not yours. |
| 429 | rate_limited | Free tools are capped per IP and per day; try later. |
| 503 | unavailable | A temporary upstream problem; retry. |
OpenAPI & manifests
- /openapi.json - OpenAPI 3.1 for every endpoint above, generated from the live tool registry
- /.well-known/agents.json - agent capability manifest
- /llms.txt - site overview for LLMs