What Is the Grok API guidelines Parameter? Custom Content Moderation, Explained

xAI added a guidelines parameter to the Grok text API, letting you tell the model to further moderate specific content categories as it writes. If you build on Grok and need tighter control over sensitive output, this is the first in-request content control xAI ships for text. Here's exactly what the Grok API guidelines parameter does, which categories it covers, how to set it, and the request limits and errors to plan for.

What the guidelines parameter does

The guidelines parameter is an array you add to a Grok text API request to change how the model handles certain content categories. For each category you list, you pick an enhanced behavior; Grok then follows the guidelines as it writes its response, in its own words. The response has the same shape as a normal response — there's no extra wrapper to parse.

Two things matter here:

• It's opt-in per category. Any category you leave out keeps the model's default moderation behavior, so you only list the categories you actually want to change.
• It's per request. Guidelines apply only to the request that carries them. To cover a whole conversation, you send them on every request in that conversation.

The feature was documented on the Grok API release notes in October and, per xAI's announcement, is available to all API customers.

Which categories and behaviors are supported

Each entry in guidelines has three fields: type (always "policy"), a category, and the behavior you want for it. Today the only behavior is decline.

The docs describe these behaviors at a high level and note xAI may refine the details over time. The practical takeaway: decline is a softer, in-the-response steer, not a hard classifier that returns an error — Grok reshapes its own answer to stay inside the category you named.

How to set guidelines on a request

You pass guidelines as a top-level array. On the Responses API it sits alongside your other parameters; on Chat Completions it goes at the same level as messages. Here's a request that sets both violence and nsfw to decline:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "input": "Write a short story about a knight.",
    "guidelines": [
      { "type": "policy", "category": "violence", "behavior": "decline" },
      { "type": "policy", "category": "nsfw", "behavior": "decline" }
    ]
  }'

SDK notes that trip people up:

• OpenAI Python SDK: the field isn't defined, so pass it in extra_body.
• OpenAI JavaScript SDK: send guidelines with your other request parameters.
• xAI Python SDK: chat.create stores the guidelines on the chat, so every sample() call sends them automatically — you don't repeat them yourself.

Which APIs support it — and which don't

guidelines is accepted on Chat Completions, the Responses API, and chat.create in the xAI Python SDK. It does not work in a few cases, and the API rejects those requests with a 400 before the model runs:

• Multi-agent models, such as grok-4.20-multi-agent.
• Deferred completions.
• A request with no server-side tools and no file attachments that also sets stop, or sets n greater than 1.

Because the check happens up front, a rejected request costs you no model inference — but it does mean you need to catch these errors in code.

Errors to expect

The API validates guidelines before running the model and returns an error if it can't apply them:

In the xAI Python SDK, an unknown category or behavior raises a ValueError before the request is even sent; the other errors come back as a gRPC INVALID_ARGUMENT status.

Why this matters for developers

Grok has historically been positioned as a more permissive model, and text API calls previously had no in-request moderation controls — you took the model's default behavior or filtered output yourself. The guidelines parameter is a middle path: category-level steering you declare inline, with no separate moderation call and no threshold logic in your own code.

It's deliberately narrow right now — three categories, one behavior (decline), text only. For a customer-facing chatbot where you can't risk sexualized or graphically violent output, declaring nsfw and violence as decline is a one-line guardrail. For anything stricter or more auditable, you'll still want your own output checks, since decline reshapes the response rather than hard-blocking it — and you should still handle the 400/422 rejections above.

Build moderated AI workflows with your own agents

Content controls like Grok's guidelines parameter are one piece of running AI safely in production — the harder part is wiring a model's output into real tasks, approvals, and tools. Eigent is an open-source multi-agent "Cowork" app that runs an AI workforce locally, so you can keep sensitive prompts and data on your own machine while agents handle the workflow with human-in-the-loop checkpoints. See how that fits a lean team in running a one-person company with AI agents, or download Eigent to try it.