> For the complete documentation index, see [llms.txt](https://help.rankability.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.rankability.com/api/api-serena-consultation.md).

# Serena consultation API and MCP tool

Ask Serena client-scoped strategic questions from an external assistant or automation through a read-only Agent API and MCP contract.

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](/api/api-authentication.md), 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](/api/mcp-getting-started.md) first.

## Scope and endpoints

The API key or OAuth grant needs `serena:ask`.

```http
POST /api/agent/v1/serena/consult
```

MCP exposes the same contract as `consult_serena`.

## Request

```json
{
  "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](/api/api-getting-started.md):

```bash
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. The response reports which grounding layers were included and lists any public Help Center sources used for product facts.

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:

```json
{
  "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,
    "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.

## 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.