openshield docs

AI coding agents

Hand the integration to your coding agent with a ready prompt, llms.txt and the OpenAPI document.

An AI coding agent can wire openshield into your project in minutes, if it has the right facts. These pages give it three things. To check what an agent itself reads and writes, see Moderate an AI agent.

The prompt

The dashboard builds an integration prompt for your organization, with its API base URL, the documentation links and the workflow you pick. You find it in the dashboard under Get started, with a copy button and a curl example next to it.

The prompt asks the agent to:

  1. list every place where users upload images or submit text that other people can see;
  2. add one server-side moderation module, with a timeout, that calls POST /v1/image and POST /v1/text;
  3. act on summary.action: go on for accept, keep the content hidden for review, refuse it for reject with a message chosen from the reason's id;
  4. handle errors: refuse for 400, 413 and 415, log and alert for 401 and 403, retry after Retry-After for 429 and 503, and fail closed for anything else;
  5. write tests with the HTTP call stubbed.

The prompt never contains your key. It tells the agent to read the key from the OPENMOD_API_KEY environment variable, and never to hard-code it, log it or send it to a browser. Put the key in your server's environment yourself.

llms.txt and llms-full.txt

These docs publish the machine-readable files that agents look for:

Every page is also available as raw Markdown, at https://openshield.dev/raw/docs/<page>.md: for example /raw/docs/quickstart.md.

The OpenAPI document

The API is described by an OpenAPI 3.1 document, generated from the gateway's code, so it is always the document of the running version:

  • https://api.openshield.dev/openapi.json, from the API itself;
  • /docs/api/openapi.json, a copy published with these docs.

Most agents and code generators can read it directly.

Tips for good results

  • Name the workflow in the prompt if you use one other than default.
  • Ask the agent to show you the list of places it will moderate before it changes code.
  • Review what it writes about failures: the safe default is to hold content when a check cannot be made, not to publish it.

Moderate an AI agent

Check what an agent reads and what it writes with two calls and a fallback, so nothing unchecked reaches the model or the reader.

Best practices

Server-side only, fail closed, downscale images, and show users messages you choose by category id.