Semji

Find a content draft by ID, or search content drafts in a workspace when ID is omitted. With `id`, returns the content metadata (status, assignee, page, last generation) — pass `include` to fetch the HTML body or the version history. Every content in Semji is wrapped by a page (auto-created shell page if no URL); the returned `pageId` is what you pass to launch-agent for a PAGE-scoped agent. Without `id`, requires `workspaceId` and supports rich filtering (title, page URL, type, status, assignee, folder, score, focus keyword, dates) and sorting. `contentScore` is the STORED score (0-100), written asynchronously — it can trail the content; read `scoreFreshness` to know whether it is `up_to_date`, `stale`, or frozen (`no_focus_keyword`/`not_started`/`not_applicable`). For a freshly recomputed score use `get-content-seo-geo-analysis`.

find-contents

Read the editor comments (threads) of a content draft, like Google-Docs comments. Returns each thread with its `anchor` (the passage of the draft the thread refers to; null for a document-level comment), its `status` (open/resolved), and its ordered `comments` (the first opens the thread, the rest are replies) with author and body. Use this to see what reviewers asked, then act on the draft with update-content and reply with reply-to-comment. Filter with `status` to focus on open threads.

find-content-comments

List past Content Ideas searches of a workspace, or get one search by ID. Pass `id` to get a single search — use this to POLL the async status (status: pending → success/failed; clusterizationStatus is the topic-clustering step). Omit `id` and pass `workspaceId` to list the search history (most recent first).

find-content-idea-searches

Read the results (content ideas) of a completed Content Ideas search. Each idea is a suggested keyword/URL with search volume, keyword difficulty, estimated traffic, similarity score, the workspace's own ranking on that keyword, its cluster(s) and whether drafts were already planned from it. Set groupBy='cluster' to nest the ideas under their AI-generated topic clusters (theme id + name) in a single call — no separate lookup needed (clusters are ready when the search's clusterizationStatus is 'success'). Supports filtering (title, url, keyword, type, keywordBrand, and gte/lte ranges on urlEstimatedTraffic, similarityScore, keywordDifficulty, searchVolume) and sorting. Default sort is by relevance (similarityScore). To turn an idea into a draft, use create-contents with the idea's keyword/url.

find-content-ideas

Read a workspace's analytics traffic broken down by channel and/or source over a date period (Content Hub › Performance › Analytics). Unlike find-page-performance (which returns one aggregated row per channel per page), this returns flat metric rows grouped by the dimensions you pass in `groupBy`: `channel` (organic/paid/direct/social/referral/ai_search/other) and/or `subChannel` (the traffic SOURCE within a channel — e.g. organic → google/bing, ai_search → chatgpt/perplexity, referral → the referring domain). Typical uses: organic sessions grouped by source → channel='organic' + groupBy=['subChannel']; only Google organic → channel='organic' + subChannel='google'. Source (subChannel) values are dynamic — discover them by grouping on subChannel first. Each row carries sessions/conversions/transactions/revenue/bounceRate/… (+ delta/evolution) and a `goals` array of the workspace's named custom conversion goals; `totals` gives the all-rows aggregate (over the full result set, not just the current page). Rows are paginated at 30 per page — check `pagination.hasMore` and request the next `page` to get them all (matters when grouping by page or subChannel on large workspaces). Metrics need the Analytics integration. The channel/source breakdown needs the 'channels' entitlement; without it you MUST pass channel='organic' (grouping by channel/subChannel without it returns permission_denied). Dates are YYYY-MM-DD.

find-page-analytics-breakdown

Read published pages WITH their performance metrics over a date period (Content Hub › Performance) — for building client reports. Same pages as find-pages, restricted to published pages, plus current + previous metrics for one metric family: `analytics` (sessions/conversions/transactions/revenue/bounceRate/…, returned as `{ total, byChannel }` — an all-channels aggregate plus one row per traffic `channel`; pass `channel` to filter to one; each row also carries a `goals` array of the workspace's named custom conversion goals — `name` + `completions` + `rate` with their delta/evolution. For a per-source breakdown within a channel, e.g. organic by search engine, use find-page-analytics-breakdown), `search` (clicks/impressions/ctr — pass `searchType` web/discover), `positions` (focus-keyword avg position + top3/10/30 distribution), or `contents` (publications count + avg content score). Each family returns an explicit, documented field set, with `*Delta`/`*Evolution` period-over-period variants. Requires periodAfter/periodBefore (YYYY-MM-DD). Metrics are compared to the immediately-preceding period of equal length by default (returned as `previousMetrics`); pass comparePeriod* to compare against a specific period instead. Metrics need the workspace to have the matching integration (Search Console / Analytics) and the Performance entitlement — otherwise they come back null. Accepts the same page filters as find-pages.

find-page-performance

Query the online pages of a workspace (Content Hub › Pages): tracked/published URLs with their Content Score, focus keyword, page type and publication state. Distinct from find-contents, which targets drafts. Supports the screen's filters (url, title, page type, focus keyword + volume/position, content score, monthly clicks/conversions/transactions/revenue, imported/published dates, planned/published/cannibalized flags, HTTP status) and sorting. Content Score is the STORED `Page.contentScore` (may lag a live re-analysis). For over-a-period performance metrics (clicks/impressions/positions with date ranges and comparison), use find-page-performance.

find-pages

Find a workspace by ID, or list all workspaces in the organization when ID is omitted. With `id`, returns the workspace metadata; pass `include` to fetch related collections (workflow statuses, folder tree, team, content counts). Without `id`, returns a flat list of all accessible workspaces. Each workspace has its own contents, keywords, folders, and team — use the returned workspaceId with find-contents, create-contents, browse-folders, etc.

find-workspaces

Read the aggregated GEO metrics behind Intel Hub GEO's Overview (workspace-wide) and a prompt's Performance tab (pass `promptId`). Returns AI-visibility metrics broken down by one `dimension`: `brands` (per tracked competitor, incl. you), `platforms` (per AI platform — REQUIRES a `brand`), or `topics` (per topic × brand grid, paginated). One `metric` per call — `visibility` (0.65×mention + 0.35×citation, default), `mention`, or `citation`; call again with another metric for the other widgets. `evolution: true` returns a time series per bucket (`brands`/`platforms` only; `periodicity` day→year, default year) instead of a single snapshot. Rates/scores are 0–100 percentages. Brand/topic/persona/funnelStage filters accept human-readable values listed in `availableFilters`; unresolvable values return an error listing them. Dates are plain YYYY-MM-DD, default last 90 days. Requires the workspace's GEO benchmark plan (a clean permission error otherwise). Note: this endpoint exposes current-period values only — no per-row deltas.

geo-metrics

Read ONE full AI answer for a tracked GEO prompt: the complete markdown answer, every brand detected in it (type: self = you, configured = tracked competitor, inferred = other) with occurrences and position, and every source used (type: citation = cited in the answer, more = additional link; isYou flags your own pages). Identify the answer by provider + date — take them from a geo-prompt `responses[].responseId` ({provider}-{date}). A null answer with a note means the run stored no answer.

geo-prompt-response

Open the detail of one tracked GEO prompt (from geo-prompts rows): its metadata, its metrics over an analysis period vs a previous one (same 0–100 / points scales as geo-prompts), and the paginated list of AI answers observed on the period — one per platform+day, with a short preview, whether YOU were mentioned/cited, and per-brand positions. Each answer row's `responseId` feeds geo-prompt-response to read the full answer. Pass `include` to fetch a subset of sections and cut cost when iterating — e.g. include:["responses"] while paginating answers; prompt metadata is always returned. `metrics: null` with a warning means no snapshot in the range (not an error). The citedBrands/mentionedBrands/providers filters apply to both the metrics and the responses sections, like the screen. Dates are plain YYYY-MM-DD; defaults: last 90 days, compared like the Intel Hub screen (previous calendar months for a month-aligned range, otherwise the same-length window shifted back). Keep responsesLimit low: each response row is expensive to produce server-side.

geo-prompt

Explore the GEO Prompts Explorer (Intel Hub GEO): the workspace's tracked prompts with their visibility in AI answers over an analysis period compared to a previous one — mention rate, citation rate, visibility score (0.65×mention + 0.35×citation), average mention position, per-prompt brand rankings, and AI-classified topic/persona/funnelStage. `kpis` aggregates the same metrics over ALL matching prompts. Rates and scores are 0–100 percentages; deltas are points vs the comparison period. Brand filters (mentionedBrands/citedBrands — include your own brand to audit your presence) and topic/persona/funnelStage accept human-readable values: valid values are listed in the response's `availableFilters`, and an unresolvable value returns an error listing them. Dates are plain YYYY-MM-DD; defaults: last 90 days, compared like the Intel Hub screen (previous calendar months for a month-aligned range, otherwise the same-length window shifted back). AI platforms not enabled on the workspace plan silently return no data.

geo-prompts

Explore the GEO Sources (Intel Hub GEO): the URLs the AI platforms rely on when answering the workspace's tracked prompts, aggregated per URL over an analysis period vs a previous one — occurrences (+delta), distinct prompts, page type, owning brand (yours, a tracked competitor, or an indirect one) and whether the URL was actually cited (vs only browsed). `kpis` aggregates total sources, distinct domains and your own sources count, with deltas. The `sources` filter accepts brand names or domains (your own brand included — audit where YOU appear) plus the special value `indirect` for sources not owned by any configured competitor; valid values are listed in availableFilters.sources and an unresolvable value returns an error listing them. Dates are plain YYYY-MM-DD; defaults: last 90 days, compared like the Intel Hub screen (previous calendar months for a month-aligned range, otherwise the same-length window shifted back). AI platforms not enabled on the workspace plan silently return no data.

geo-sources

Aggregated GEO Sources metrics (Intel Hub GEO): the distribution charts of the Sources screen — how often the AI platforms rely on sources, broken down by one dimension over an analysis period vs a previous one. `dimension` selects the breakdown: `domains` (Top domains, by owning brand's root domain — the only paginated dimension), `pageTypes` (by page type), `platforms` (by AI platform), `sourceScopes` (self = your own, configured = a tracked competitor, inferred = an indirect source). Each row is an occurrence `count`, its `percentage` share of the period total, the `countDelta` (absolute change vs the comparison period) and `countEvolution` (percent change; null when the bucket is new). Filters mirror geo-sources (providers, pageTypes, sourceTypes, sources, topic/persona/funnelStage); valid values are listed in availableFilters and an unresolvable value returns an error listing them. Dates are plain YYYY-MM-DD; defaults: last 90 days, compared like the Intel Hub screen (previous calendar months for a month-aligned range, otherwise the same-length window shifted back). AI platforms not enabled on the workspace plan silently return no data.

geo-source-metrics

Return the authenticated user, their organization, and remaining credit balances (analysis, AI writing, content ideas). Call this once at the start of a session to confirm identity and check budget.

get-account

Poll the status of the current AI content generation for a content. Status lifecycle: queued → pending → review → success (after confirm) / cancelled (after cancel). When status is "review" the generated content is ready; call resolve-content-generation with action: 'confirm' to apply it to the draft.

check-content-generation

Return the content's focus keyword (metrics + per-surface analysis status) and, when ready, the analysis scored against the content across three surfaces: `googleSearch` (SEO) and `googleAiOverview` come from the keyword analysis; `chatgpt` comes from the keyword's focus prompt analysis. Each surface block carries the overall score plus typed recommendations (topics, search intents, questions for SEO; GEO topics, cited sources, mentioned brands and the AI response preview for AI Overview and ChatGPT), and is null until its analysis is ready — check the matching *AnalysisStatus on focusKeyword/focusPrompt. The wrapping page, focus keyword and focus prompt are resolved automatically from the content. These scores are recomputed LIVE against the current draft body and may differ from the STORED `contentScore` returned by `find-contents` (which trails — see its `scoreFreshness`).

get-content-seo-geo-analysis

List brand voices configured for a workspace. A brand voice encodes tone, style, and guidelines for AI content generation. Use the returned brandVoiceId in start-contents-generation to adopt the voice. Only enabled brand voices are returned; disabled ones are filtered out. Returns all brand voices at once (no pagination). The `status` field indicates whether the voice is ready (`success`) or still being analyzed (`pending`, `error`).

list-brand-voices

List the Knowledge Base documents of a workspace (pass workspaceId) or of a specific page (pass pageId — page-attached documents do NOT appear in the workspace listing). Returns each document with its id, name, type (text/url/file), summary and processing status (pending/success/failed). Use this to discover document IDs before calling update-knowledge-document. Use find-workspaces to get the workspace ID.

list-knowledge-documents

Mark a content draft as published in Semji. This records the publication but does NOT push to an external CMS. If url is omitted, the linked page URL is used automatically. The publication URL — whether passed explicitly or derived from the linked page — must be on the workspace's configured domain, otherwise the internal API rejects the call with 'Publication URL domain does not match workspace domain'.

publish-content

Remove a member from the organization entirely, revoking all their access. This does not delete the user account, only their membership in this organization. To remove access to a single workspace instead, use manage-workspace-access with action=revoke. Resolve email with browse-users. Requires the connected user to be an organization admin. You cannot remove yourself.

remove-user

Reopen a previously resolved comment thread (unresolve). Use the threadId from find-content-comments.

reopen-comment-thread

Mark a comment thread as resolved (Semji's equivalent of archiving a comment). Only do this when the user explicitly asks to close/resolve the thread — resolving is a deliberate human decision, do not auto-resolve after replying. Use reopen-comment-thread to undo. Use the threadId from find-content-comments.

resolve-comment-thread

Resolve a pending content generation by either confirming or cancelling it. Use action: 'confirm' to accept the AI-generated text (applies it to the parent draft, generation status → 'success'); use action: 'cancel' to discard it (draft is not modified). Confirm requires the generation status to be 'review'. Cancel works for queued, pending, or review statuses (not for already completed/cancelled ones).

resolve-content-generation

Explore the SEO Data Explorer (Intel Hub SEO): the competitor top pages discovered by Search Intelligence for a workspace. Each row is a competitor URL × keyword with estimated traffic, SERP position, search volume, difficulty, the workspace's own ranking on that keyword (workspaceUrl/workspacePosition), and AI-classified topic/persona/funnelStage. `totalTraffic` sums the estimated traffic of ALL matching rows (not just the page). Dynamic filters (competitors, topic, persona, funnelStage) accept human-readable values — valid values are listed in the response's `availableFilters`, and an unresolvable value returns an error listing them. Keyword-level fields and filters only have data for the report's effective month: omit `month` to query it; other months (report.availableMonths) carry page-level data only.

seo-page-data-explorer

Read the SEO Report (Intel Hub SEO): aggregated competitor traffic metrics for a workspace, the same numbers that back the Report dashboard's charts. Each row is a competitor website × a bucket of the chosen `groupBy` axis, carrying nbPages, traffic, and the long-tail / short-tail traffic split. `groupBy` picks the aggregation: `competitor` (default, one total row per site), `brand` (branded/not_branded/branded_for_other_domain), `category` (page category), `position` (SERP position bucket), `topic` / `persona` / `funnel` (AI-classified dimensions, resolved to option names), or `month` / `monthlyProduction` (12-month series, incompatible with `month`). Dynamic filters (competitors, topic, persona, funnelStage) accept human-readable values listed in the response's `availableFilters`; an unresolvable value returns an error listing them. Use `month` (report.availableMonths) to target a specific analyzed month; omit it for the effective month. For a page-level breakdown (per keyword/URL) use seo-page-data-explorer instead.

seo-report

Create a keyword and set it as the focus keyword of the page wrapping this content, in a single step. The focus keyword drives SEO recommendations and is required before generating AI content. Optionally triggers the SEO analysis immediately so recommendations are ready when you call get-content-seo-geo-analysis. The wrapping page is resolved automatically from the content.

set-content-focus-keyword

Launch a Content Ideas search for a keyword in a workspace (Content Hub › Content Ideas). Runs asynchronously: it returns immediately with a searchId and status='pending'; poll find-content-idea-searches with that id until status='success', then read results with find-content-ideas. The search country/language are derived from the workspace. Consumes 1 'content ideas searches' credit (check the balance with get-account; some plans have unlimited). Adding an idea to the planning is done with create-contents (using the idea's keyword/url).

start-content-idea-search

Trigger asynchronous SEO analysis for a content's focus keyword. The gateway resolves the wrapping page and its focus keyword automatically — callers only pass the contentId. The analysis runs in the background (SERP scrape + recommendations computation). Call get-content-seo-geo-analysis after a few seconds to retrieve the recommendations. Each analysis consumes Analysis credits; for large bulk runs, check the balance with get-account first.

start-content-seo-geo-analysis

Launch AI content generation (Atomic Content) on one or more content drafts. The backend queues the jobs asynchronously. The tool returns one entry per input contentId with a `tracked` boolean that reflects whether THIS call actually queued a new generation: `tracked=true` means the backend created a new generation for this content (poll its `status` with check-content-generation); `tracked=false` means the backend did not start a new generation for this content and the entry carries a `reason` explaining why (no focus keyword / SEO analysis not 'success' / a prior generation is already in flight / a stale terminal generation is attached). When a prior in-flight generation blocked the call, you can still poll check-content-generation on the same contentId to observe its progress. Each target content must be linked to a page with a focus keyword whose SEO analysis is complete. Use type='optimize' to improve existing HTML, type='replace' to regenerate from scratch. Use retry=true to relaunch previously failed generations. Consumes AI Writing credits — the exact cost varies with generation type, fact-checking, and brand voice; check the remaining balance with get-account before bulk runs. Poll each result via check-content-generation.

start-contents-generation

Update an existing content draft. Only fields you pass are updated. Concurrency is handled server-side: the gateway fetches the latest version transparently before writing, so callers never need to deal with optimistic locking. Last-write-wins on simultaneous edits. The assignee is identified by email (resolved server-side against the organization).

update-content

Rename a folder or move it under a different parent. Pass only the fields you want to change. Set parentFolderId to null to move to the root.

update-folder