Semji

List the AI agents configured in a workspace (AgentHub). Each agent has an `id` (pass it to launch-agent), a `type` (e.g. CONTENT_LOCALIZER, GEO_EXPERT, EEAT_AUDITOR…), a `scope` ('PAGE' = runs on a specific page, 'WORKSPACE' = runs at workspace level) and an `enabled` flag. Use this to discover which agent to launch.

find-agents

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`. In list mode (no `id`), each content also carries its Google AI Overview presence for the page's focus keyword (`aioState`: cited/not_cited/no_aio, plus `aioCitedUrl`) and the date of the last SERP (`aioAnalyzedAt`).

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. Each page row also carries its Google AI Overview presence (`aioState`: cited/not_cited/no_aio, plus `aioCitedUrl`) and the date of the last SERP (`aioAnalyzedAt`).

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). Each page also carries its Google AI Overview presence for the focus keyword (`aioState`: cited/not_cited/no_aio, plus `aioCitedUrl`) and the date of the last SERP (`aioAnalyzedAt`). 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 Intelligence 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 Intelligence 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 (Intelligence 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 Intelligence 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 (Intelligence 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 Intelligence 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 (Intelligence 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 Intelligence 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 text is already written into the draft, the previous body being kept in the content's version history; call resolve-content-generation with action: 'confirm' to accept it.

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

Invite a user to the organization by email and grant them access to one or more workspaces, in a single call. The invitation is sent asynchronously by email; the user is added at the plan's default workspace role (MEMBER on most plans; plans without the member role assign OWNER). Workspaces the user already has access to are left unchanged. Use find-workspaces to get workspace IDs and browse-users to check existing members first. Requires the connected user to be an organization admin.

invite-user

Launch a Semji AI agent (from find-agents) with a free-text instruction. Runs ASYNCHRONOUSLY: this opens a thread and queues the run, returning immediately with a threadId + messageId + status='pending' (+ a webUrl deep link to the conversation in the Semji editor for PAGE-scoped runs). Poll check-agent-run with the threadId until status is 'completed' (or 'failed'/'stopped') to read the output. PAGE-scoped agents require a pageId (the page they run on); WORKSPACE-scoped agents ignore it — the correct endpoint is resolved automatically from the agent's scope. Consumes AI-writing credits (check the balance with get-account). To continue the conversation, use reply-to-agent on the same threadId — do NOT launch again (that opens a new thread and loses context). To run one agent on MANY contents at once, use launch-agent-bulk.

launch-agent

Launch a PAGE-scoped Semji agent (from find-agents) on MANY contents in ONE call — one async run per eligible content. Pass the workspaceId, the agentId, and the contentIds to target (from find-contents / find-pages). Returns a `bulkActionId` plus counts: `requested` (targeted), `scheduled` (eligible runs created — a content is eligible when its page has a successfully-analysed focus keyword), `skipped` (requested − scheduled). Track the batch with check-agent-batch(bulkActionId), then read each finished run's summary with check-agent-run(threadId). Consumes AI-writing credits per scheduled run; if credits are insufficient, the agent is out of plan, or AI access is denied, NOTHING is created and the error explains why. For a single content, launch-agent is simpler.

launch-agent-bulk

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

Manage an organization member's access to a workspace. action='grant' adds the member to the workspace at the plan's default role (MEMBER on most plans; plans without the member role assign OWNER) and sends them an invitation email — use it to add an existing member to an additional workspace; a member who already has the access is left unchanged. action='set-role' changes an existing access's role (role required). action='revoke' removes the member's access to the workspace. Resolve email with browse-users and workspaceId with find-workspaces. grant works for a workspace owner or an organization admin; set-role and revoke require the connected user to own the target workspace.

manage-workspace-access

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

Continue an agent conversation by posting a follow-up message to an existing thread (from launch-agent). The agent answers with the full thread context. Runs ASYNCHRONOUSLY like launch-agent — poll check-agent-run for the result. Fails if a run is already in progress on the thread (only one active run per thread — wait until check-agent-run shows a terminal status). Consumes AI-writing credits.

reply-to-agent

Reply to an existing comment thread on a content draft. Use the threadId from find-content-comments. Posting a reply notifies the thread participants by email. Returns the new commentId.

reply-to-comment

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. The generated text is written into the draft as soon as the generation reaches 'review', right after the previous body is saved as a version in the content's version history (listed by find-contents with include: ['versions'], restorable from the History panel of the Semji editor). Use action: 'confirm' to accept that text (generation status → 'success'): it writes nothing more to the draft. Use action: 'cancel' to stop a queued or pending generation before it touches the draft. Cancelling in 'review' only marks the generation cancelled: the generated text stays in the draft until the previous version is restored. 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 (Intelligence Hub SEO): the competitor top pages discovered by Intelligence Hub SEO 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), the AI Overview presence for that keyword — the workspace's (aioState: cited/not_cited/no_aio, plus aioCitedUrl/aioPosition), the competitor page's (competitorAioState/competitorAioCitedUrl/competitorAioPosition), and the last-SERP date (aioAnalyzedAt) — 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 (Intelligence 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

Set the focus prompt of the content's focus keyword — the AI-search query whose ChatGPT (GEO) analysis feeds the `chatgpt` surface of get-content-seo-geo-analysis. Creates the prompt from the given text (or reuses an identical one) and points the focus at it. Requires a focus keyword on the wrapping page — set one with set-content-focus-keyword first. Run start-content-focus-prompt-analysis afterwards to analyse it.

set-content-focus-prompt

Trigger the ChatGPT (GEO) analysis of the content's focus prompt. The gateway resolves the wrapping page and its focus prompt automatically — callers only pass the contentId. The analysis runs in the background; poll get-content-seo-geo-analysis afterwards (its `chatgpt` block and `focusPrompt.chatgptAnalysisStatus` update when ready). Requires a focus prompt — set one with set-content-focus-prompt first. Each analysis consumes Analysis credits.

start-content-focus-prompt-analysis

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