Serena consultation API and MCP tool

Use Serena consultation when another assistant, such as Codex or Claude, needs Rankability’s strategic reasoning. The host assistant keeps the broader conversation and decides when to consult Serena. Serena returns one grounded answer for the selected client.

Before calling it, create an API key or OAuth grant with the least-privilege scope described in Authentication and API scopes, and obtain the client UUID with GET /api/agent/v1/clients. If you are connecting an assistant through MCP, complete Connecting Rankability to AI assistants with MCP first.

Scope and endpoints

The API key or OAuth grant needs serena:ask.

POST /api/agent/v1/serena/consult

MCP exposes the same contract as consult_serena.

Request

{
  "client_id": "11111111-1111-4111-8111-111111111111",
  "question": "What should we prioritize over the next 30 days?",
  "history": [
    { "role": "user", "content": "Focus on qualified leads." }
  ]
}

client_id and question are required. history is optional and accepts up to 10 recent Serena-specific user or assistant turns. The host assistant normally retains the rest of the conversation.

Send the request with the same Bearer authentication described in Getting started with the Agent API:

curl -X POST "https://app.rankability.com/api/agent/v1/serena/consult" \
  -H "Authorization: Bearer $RANKABILITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "11111111-1111-4111-8111-111111111111",
    "question": "What should we prioritize over the next 30 days?"
  }'

Do not place an API key directly in source code, shell history, logs, screenshots, or client-side JavaScript.

Grounding and response

Serena can use the client’s selected completed Knowledge sources, saved workspace activity, durable client memory, Rankability methodology, relevant SOP skill guidance, and canonical Help Center articles. Saved workspace activity includes a short summary of the latest Tracker results for the client’s scheduled reports: which AI platforms name or cite the client, Maps pack and organic positions, competitors named instead, and the top actionable citation source URLs. Paused, retired, and one-time Tracker reports are labeled separately and are not counted as tracked. The response reports which grounding layers were included and lists any public Help Center sources used for product facts.

Help Center articles are attached only when the question is about using Rankability, or when an article closely matches the question. Client strategy questions usually return an empty help_center_sources list. Each source includes a relevance value from 0 to 1: the share of the question’s terms found in that article’s title, category, or summary.

The answer preserves missing and unavailable evidence instead of turning it into a zero or estimate. Private coaching, doctrine, and SOP retrieval remains unattributed and is expressed as Serena’s own strategic judgment.

A successful response follows this shape:

{
  "answer": "Start with the measured constraint...",
  "client_id": "11111111-1111-4111-8111-111111111111",
  "requested_model": "gpt-5.6-terra",
  "contract_version": "1.0",
  "grounding": {
    "client_knowledge_sources": 3,
    "knowledge_inspection": {
      "mode": "bounded_context",
      "input_complete": false,
      "full_review_available": false,
      "max_context_characters": 40000
    },
    "workspace_activity": "included",
    "client_memory": "included",
    "methodology": "included",
    "sop_skill": "included",
    "help_center_sources": []
  },
  "limitations": [
    "This consultation is read-only and did not execute or schedule Rankability actions."
  ],
  "usage": {
    "prompt_tokens": 1800,
    "completion_tokens": 420,
    "total_tokens": 2220
  }
}

Grounding status describes what was available for that answer, not a quality score. Token counts can be null when the reasoning provider does not return usage metadata. requested_model identifies the Rankability model requested by the service; provider fallback can still occur.

Long documents and complete review

Ordinary consultation uses bounded Knowledge excerpts. A source count, successful full-source readback, or matching file hash does not prove that Serena inspected every section. When document review is enabled for the deployment, ordinary questions use relevant original sections, with saved section understanding helping locate evidence.

grounding.knowledge_inspection reports the ordinary consultation’s context ceiling and deployment availability. Its input_complete=false means no complete-review receipt was produced; it is not a claim that the stored document is damaged. The 40,000-character ceiling is shared by the client profile and selected-source context, not an allowance for each source.

Knowledge embedding_status=pending and chunk_count=0 are indexing metadata, not proof of a failed import or an active indexing job. Ordinary MCP consultation and exact section reads use original stored text without requiring embeddings. Ask Support to check indexing configuration separately; do not repeatedly import the source to try to repair partial consultation context.

For exact original passages, use MCP get_client_source_section or GET /api/agent/v1/clients/:client_id/sources/:source_id/sections (clients:read). Omit section to get the complete map, then pass one zero-based section index. Each returned section reports its SHA-256 and exact character, byte and line ranges. Character offsets are zero-based UTF-16, half-open; byte offsets refer to UTF-8; lines are one-based. This reader does not start a model review.

Where enabled, request a full section-by-section review with MCP review_knowledge_document or POST /api/agent/v1/serena/document-reviews (serena:ask):

{
  "client_id": "11111111-1111-4111-8111-111111111111",
  "question": "Inspect all eight required evidence blocks and state any unsupported requirement.",
  "source_ids": ["22222222-2222-4222-8222-222222222222"],
  "confirm_review": true
}

Omit source_ids to use selected completed Knowledge sources. Questions are limited to 4,000 characters; a review accepts up to 20 sources, 500,000 characters total and 80 sections. Larger requests are rejected, not silently truncated. This usage-bearing background work returns a review_id; poll MCP get_knowledge_document_review or GET /api/agent/v1/serena/document-reviews/:review_id?client_id=... for the saved answer. In Ask Serena, request a complete review and then ask for the latest review status.

Queued or processing work is not complete. input_complete=true is returned only for complete, current section coverage. All original sections are supplied to individual review calls; the final response combines their findings, rather than seeing all raw text simultaneously. This establishes input coverage, not perfect understanding or complete external-fact verification. Changed sources make prior results stale and withhold their answers. Failed or unavailable results do not claim completion. Identical unchanged requests reuse the same saved review; different full-review questions require fresh inspection. This capability does not edit sources, publish, or require re-importing them. A disabled deployment returns document_review_disabled instead of starting work.

Read-only boundary

Consultation does not start scans, run audits, crawl pages, change projects, publish content, or perform live web research. If Serena recommends an action, call the separate scoped tool, show its usage impact when applicable, and obtain the normal confirmation before execution.

The endpoint is synchronous. Handle these common responses:

• 400 invalid_input — validate the UUID, non-empty question, history roles, and length limits.
• 401 invalid_token — replace or reconnect the credential; do not retry the same invalid token.
• 403 insufficient_scope — grant serena:ask; an existing OAuth grant must be reauthorized before it receives a newly added scope.
• 404 not_found — the client does not exist in the authenticated organization, or the caller cannot access it.
• 429 rate_limited — wait for the returned retry window before calling again.
• 503 feature_unavailable — Serena consultation is disabled for the current deployment. Reauthorizing, changing scopes, or retrying will not enable it; contact Rankability support.
• 503 serena_unavailable — a transient grounding or reasoning dependency failed; retry after a short delay.

Use a bounded retry policy for 429 rate_limited and 503 serena_unavailable responses. Do not automatically retry authentication, permission, validation, or feature_unavailable failures.

For a hypothetical or supplied-evidence-only question, Serena excludes workspace knowledge, memory, campaign and activity reads. grounding.workspace_activity is excluded, distinct from a failed or unavailable read. An explicit request to also inspect actual workspace evidence retains those reads.