How to Create Custom Amazon Q Plugins for Internal Docs

November 20, 2026

Amazon Q Business plugins let the assistant call your own internal APIs instead of only reading indexed documents. You register an OpenAPI 3.0 schema, point it at a Lambda or internal endpoint, grant Q the right IAM permissions, and the assistant can then answer \”what’s the status of ticket 4821\” with live data.

Indexing documents is the easy half. Plugins are the half where projects stall, because a plugin that returns untidy JSON makes Q invent a summary.

When does a plugin beat just indexing the data?

Index it when the content is mostly static prose that changes monthly — policies, runbooks, onboarding guides. Use a plugin when the answer changes hourly or depends on who asks.

Three signals that you need a plugin:

  • The data is already behind an API and duplicating it into an index goes stale within a day.
  • Answers must respect per-user permissions at query time, not at index time.
  • The user needs an action (create a ticket, look up an order), not just a summary.

Amazon Q Business does support document-level ACLs on indexed content, so permissions alone is not a strict plugin case. Freshness usually is.

Step 1: Write the OpenAPI schema before the code

Amazon Q reads an OpenAPI 3.0 spec and turns each operation into something the assistant can call. The schema is the prompt. Vague descriptions produce bad routing.

A workable skeleton for a ticket lookup:

  • operationId: getTicketStatus — never generic words like get or lookup
  • summary: \”Returns the current status, assignee and last update time for a support ticket\”
  • parameters: ticket_id as a string, required, with an example value
  • response schema: explicit types, no free-form objects

Keep descriptions in plain sentences that name the entity. Amazon Q matches user intent against the summary text, so \”Returns the current status, assignee and last update time for a support ticket\” routes reliably; \”Gets ticket\” does not.

Aim for fewer than ten operations per plugin. Beyond that, routing accuracy drops and users get the wrong tool called.

Step 2: Choose the auth method

Q Business plugins support three auth paths, and picking wrong is the most common reason a working local test fails in production.

Method Use when Gotcha
No auth internal endpoint already on a private VPC only works if Q reaches it over the same network
API key third-party or legacy internal API key stored in Secrets Manager, rotated manually
OAuth 2.0 per-user permissions matter the consent flow is per user, not per application

For anything where the answer depends on the asker, OAuth is the answer. An API key means every user sees every ticket, which is a security incident waiting for a quiet Tuesday.

The IAM role Q uses needs execute-api:Invoke on your API Gateway plus, for API-key plugins, secretsmanager:GetSecretValue on the exact secret ARN. Broad permissions like secretsmanager:* get flagged in most security reviews.

Step 3: Register and test the plugin

In the Q Business console, open the application, go to Integrations → Plugins, and add a custom plugin. Upload the OpenAPI spec as JSON or YAML and fill in the auth block.

Test with Amazon Q’s built-in plugin test console rather than the chat. The test console shows the request Q would send, which exposes schema problems in seconds. The chat interface hides them behind a confident but wrong answer.

Then test through chat with three phrasings of the same question. If Q can only route the exact phrase from your spec, the descriptions need work, not the model.

Step 4: Control what Q does with the response

This is the piece most teams miss. Q synthesizes the API response into prose. If your endpoint returns a 200 with {"error": "not found"}, Q will tell the user something plausible about a ticket that does not exist.

Return proper HTTP codes. 404 for missing records, 403 for permission failures, 500 only for genuine faults. Q reads status codes and relays failures more accurately than it reads error text.

Trim the payload too. Ten fields with clear names beat a 60-field database row; the extra fields invite the assistant to mention them.

What does this cost in practice?

Q Business is licensed per user, starting around $20 per user per month for the Business edition, and plugin calls are charges on top — small, but not zero if your users hammer a lookup. The bigger cost is engineering: a plugin with auth, testing and schema tuning is one to two days of work per integration.
Also check the region. Q Business is available in a subset of AWS regions, and a plugin endpoint in an unsupported region will not connect regardless of IAM. Verify your application region first.

Who this works for, and who should skip it

Good fit: enterprises already on AWS with an API layer in front of internal systems — ticketing, orders, inventory, HR records. Teams with an internal developer portal see the fastest payoff, since the data is already well-modelled.
Skip it if your data lives in a wiki that changes twice a year. Indexing with the built-in connectors takes an afternoon and answers most questions; a plugin adds a maintenance burden for no gain.
Also skip if you cannot support OAuth. Without per-user auth, a ticket assistant becomes a data leak, and no amount of schema tuning fixes that.
An honest drawback: debugging is thin. When a plugin fails, Q reports that the action failed without showing the upstream HTTP response, so you will end up correlating CloudWatch logs with timestamps to find the cause.

Quick Summary

  • Amazon Q Business plugins call your own APIs through an OpenAPI 3.0 schema and replace document indexing when data changes hourly.
  • Write descriptive operationIds and summaries — the schema doubles as the routing prompt.
  • Use OAuth 2.0 whenever answers depend on who is asking; an API key exposes everything to everyone.
  • Return real HTTP status codes; Q relays 404 and 403 more reliably than error text in a 200 body.
  • Business licensing starts near $20 per user per month plus small per-call charges.
  • Expect one to two days of engineering per plugin, and thin error visibility when it breaks.