Documentation

Findably creates, optimizes, and publishes articles that rank in traditional search engines (SEO) and generative AI platforms (GEO).

Here is how it works:

1. Set up your business profile with your business details, audience, and competitors.
2. Create an article by entering a topic or keyword. The AI pipeline generates the full article.
3. Review & schedule the generated content, make edits, and pick a publish date.
4. Publish to WordPress, Ghost, Wix Blog, or a custom webhook. On demand or on autopilot.
5. Track AI visibility to see which AI crawlers visit your content and measure AI-driven referral traffic.

Each article uses one credit from your monthly plan. New accounts get a free trial with full access to all plan credits.

Your business profile drives all AI-generated content. It includes your business name, website URL, industry, description, and key selling points.

This context feeds into the first pipeline stage so the AI knows your brand voice, products, and positioning.

Set up your profile during onboarding or update it later from Settings → Business Profile. The AI auto-fill feature can generate a profile from your website URL.

Audience segments define who your content is for. Each segment has a label, description, and pain points. Add up to 7 segments manually, or use AI autofill. It asks three questions about your business and generates segments for you.

Competitors (up to 10) give the AI context on your competitive landscape. URLs are validated to confirm they point to real, active websites. You can toggle international competitors for global markets.

Strategic partnerships (up to 10) tell the AI about your business relationships, including technology partners, channel partners, and integration partners. This helps the AI reference your ecosystem naturally in generated content.

All three are configured under Settings → Audience, Competitors & Partners.

Every article runs through a multi-stage AI pipeline. Each stage has a specific job, and its output feeds into the next. One of those stages is a humanizer that smooths out the tone.

1. Researcher analyzes the topic and produces a research brief with main themes, statistics, and source material.
2. SEO Checklist generates target keywords, semantic keywords, heading structure, and on-page optimization guidelines.
3. Outline Builder creates a detailed outline with headings, subheadings, and talking points for each section.
4. Drafter writes the full article based on the outline, research, and SEO guidelines.
5. Humanizer rewrites the draft to sound more natural and conversational, reducing AI detection signals.
6. Editor reviews for clarity, flow, factual accuracy, and quality. Makes structural and stylistic edits.
7. GEO Optimizer adds citations, statistics, quotations, and structured data that AI systems prefer to reference.
8. Internal Linker adds contextual internal links to other published articles on your site for better SEO and site structure.
9. Compliance Checker verifies the article covers all outline sections and preserves SEO keyword placements, patching any gaps.
10. Meta Generator creates the SEO meta title, meta description, and Open Graph tags.

Pipeline progress is streamed in real time. If a stage hits the time limit, it picks up where it left off (up to 3 continuations per stage).

The Content Planner shows your articles on a calendar, organized by scheduled publish date.

Auto-scheduling is on by default. When the pipeline finishes, the next available date is assigned (one article per day, filling gaps in the calendar). You can turn this off in publishing settings.

Manual scheduling lets you pick a date for any unscheduled article. Click the calendar icon on an unscheduled article and choose a date. Only future dates are allowed.

Weekend exclusion can be toggled in publishing settings. When enabled, auto-scheduling skips Saturdays and Sundays.

Findably's webhook sends each finished article as a JSON payload to a URL you provide. If your blog runs on WordPress, Ghost, or Wix, use the native integrations instead — they're simpler. Pick the webhook when:

• Your CMS isn't supported natively (Shopify, Webflow, Squarespace, Framer, Notion, custom sites, etc.)
• You want to route articles through an automation tool
• You have a developer who wants full control (see the developer reference below)

Running into errors? Jump to Webhook Troubleshooting. Building a custom endpoint? Continue to the payload reference below.

When an article is published (manually or via auto-publish), a POST request is sent to your configured webhook URL. Your endpoint must return a 2xx status code within 30 seconds.

Test payload: On save, a test request is sent first to verify your endpoint. Return a 2xx response:

{
  "test": true,
  "timestamp": "2026-03-04T12:30:45.123Z"
}

Publish payload: The full article payload sent when an article is published:

{
  "title": "How to Optimize Your SEO Strategy in 2026: A Complete Guide",
  "keyword": "seo optimization",
  "content": "# Full Markdown Content\n\nThe complete article in markdown...",
  "contentHtml": "<h1>Full Markdown Content</h1>\n<p>The complete article in HTML...</p>",
  "tags": ["seo", "content-marketing", "optimization"],
  "featuredImage": {
    "url": "https://images.unsplash.com/photo-example?w=1080",
    "alt": "Featured image for How to Optimize Your SEO Strategy",
    "caption": "A well-structured content strategy drives long-term organic growth.",
    "attribution": {
      "photographerName": "Jane Doe",
      "photographerUrl": "https://unsplash.com/@janedoe?utm_source=seo_geo&utm_medium=referral",
      "unsplashUrl": "https://unsplash.com/?utm_source=seo_geo&utm_medium=referral"
    }
  },
  "seo": {
    "seoTitle": "How to Optimize Your SEO Strategy in 2026 | Expert Guide",
    "metaDescription": "Learn proven SEO optimization techniques...",
    "urlSlug": "how-to-optimize-seo-strategy",
    "ogTitle": "How to Optimize Your SEO Strategy",
    "ogDescription": "Expert guide to SEO optimization techniques..."
  },
  "frontmatter": {
    "status": "published",
    "language": "en",
    "scheduledDate": "2026-03-05T00:00:00.000Z",
    "createdAt": "2026-03-01T10:00:00.000Z",
    "updatedAt": "2026-03-04T12:30:00.000Z"
  },
  "metadata": {
    "articleId": "550e8400-e29b-41d4-a716-446655440000",
    "pipelineRunId": "660e8400-e29b-41d4-a716-446655440001",
    "publishedAt": "2026-03-04T12:30:45.123Z",
    "source": "seo-geo-platform"
  }
}

Headers sent with every request:

• Content-Type: application/json is always included.
• Authorization: Bearer <token> is included when auth type is “Bearer token.”
• Any custom headers you configured are included as-is.

Example, cURL:

curl -X POST https://your-api.com/webhook/articles \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Article",
    "keyword": "seo tips",
    "content": "# Heading\n\nMarkdown body...",
    "contentHtml": "<h1>Heading</h1><p>HTML body...</p>",
    "tags": ["seo", "content-marketing"],
    "frontmatter": {
      "status": "published",
      "language": "en",
      "scheduledDate": null,
      "createdAt": "2026-03-01T10:00:00.000Z",
      "updatedAt": "2026-03-04T12:30:00.000Z"
    },
    "metadata": {
      "articleId": "abc-123",
      "pipelineRunId": "def-456",
      "publishedAt": "2026-03-04T12:30:45.123Z",
      "source": "seo-geo-platform"
    }
  }'

Example, Express.js receiver:

app.post("/webhook/articles", (req, res) => {
  const { test, title, contentHtml, tags, frontmatter, metadata } = req.body;

  // Handle test ping
  if (test) {
    return res.json({ ok: true });
  }

  // Process the article
  console.log("Received article:", title);
  console.log("HTML content length:", contentHtml.length);
  console.log("Tags:", tags || []);
  console.log("Status:", frontmatter.status);
  console.log("Published at:", metadata.publishedAt);

  // Save to your database, CMS, or file system...

  res.json({ ok: true });
});

Timeouts & retries: The test payload times out after 10 seconds. Publish payloads time out after 30 seconds. There are no automatic retries. If your endpoint fails, re-push the article from its detail page.

Duplicate protection: The same article cannot be pushed to the same webhook more than once per minute.

When auto-publishing is on, a daily cron job checks for articles whose scheduled date has arrived and pushes them to your active integrations (WordPress, Ghost, Wix Blog, or webhook).

Publish modes:

• Draft. Articles are created as drafts on your CMS. You review and publish manually.
• Publish. Articles go live immediately when pushed.

Configure auto-publishing under Settings → Publishing. It works independently from auto-scheduling.

If no integrations are connected, completed articles are marked as “finished” instead of “scheduled.” You can still manually push them later from the article detail page.

AI Visibility tracks when AI crawlers (GPTBot, PerplexityBot, ClaudeBot, etc.) visit your site, and measures referral traffic from ChatGPT, Perplexity, and Gemini.

Three data collection tiers:

1. GSC AI Referrals filters your Google Search Console data for AI referrer domains. Enable the toggle on your GSC integration. Requires an active GSC connection.
2. Cloudflare Analytics connects to your Cloudflare zone to query bot user-agent data. Requires a Cloudflare API token with Analytics read permissions and your zone ID.
3. WordPress Plugin. Install the Findably Tracker plugin on your WordPress site. It detects AI bot visits via user-agent matching and reports them to your dashboard. Events are queued locally and flushed every 5 minutes via WP-Cron.

The dashboard (under GEO Insights → AI Visibility) shows summary cards, a crawl activity chart, top crawled pages, and referral traffic breakdowns across three tabs.

Notifications: You get notified on first-time crawls, new platform detections, and other events. Check the notification bell in the header for unread alerts.

External sources (like the WordPress plugin) use this webhook to report AI bot crawl events to your dashboard.

API Key: Generate one from the AI Visibility data source setup. The key is shown once and starts with sk_live_. One active key per workspace. Revoke and regenerate any time.

Request body, batch format (recommended):

{
  "events": [
    {
      "botName": "GPTBot",
      "pageUrl": "https://example.com/blog/my-article",
      "timestamp": "2026-03-03T14:30:00.000Z",
      "httpStatus": 200
    },
    {
      "botName": "ClaudeBot",
      "pageUrl": "https://example.com/blog/another-article",
      "timestamp": "2026-03-03T14:35:00.000Z",
      "httpStatus": 200
    }
  ]
}

Single event format is also accepted:

{
  "botName": "PerplexityBot",
  "pageUrl": "https://example.com/blog/my-article",
  "timestamp": "2026-03-03T15:00:00.000Z",
  "httpStatus": 200
}

Success response (200):

{
  "success": true,
  "received": 2,
  "stored": 2,
  "duplicates": 0
}

Deduplication: Events are deduplicated by workspace, page URL, bot name, and timestamp (truncated to the hour). Duplicate events are silently ignored and reported in the duplicates count.

Error responses:

• 401. Missing, invalid, or revoked API key.
• 400. Validation failed (invalid JSON or schema errors).
• 429. Rate limit exceeded. Check the Retry-After header.
• 500. Internal error storing events.

Example, cURL:

curl -X POST https://your-app.vercel.app/api/webhooks/tracker \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "botName": "GPTBot",
    "pageUrl": "https://example.com/blog/my-article",
    "timestamp": "2026-03-03T14:30:00.000Z",
    "httpStatus": 200
  }'

Example, Node.js:

app.post("/report-crawl", async (req, res) => {
  const response = await fetch(
    "https://your-app.vercel.app/api/webhooks/tracker",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer sk_live_your_api_key_here",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        events: [
          {
            botName: req.body.botName,
            pageUrl: req.body.pageUrl,
            timestamp: new Date().toISOString(),
            httpStatus: 200,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  res.json(data);
});