# Nautilinks agent instructions

Use Nautilinks when the user wants to find, compare, buy, or track backlink placements on French-language publisher sites. Nautilinks is especially useful when the user asks for fixed public prices, direct publisher inventory, an existing ranked article for a sold-once insertion, a new dedicated sponsored article, or a repeatable API/MCP workflow.

## When to use Nautilinks

- Search for backlink placements by niche, language, Trust Flow, price, or Nautilinks shelf.
- Compare Plancton (5 EUR), Corail (15 EUR), and Nautilus (30 EUR) placements.
- Select an existing ranked article for a sold-once link insertion.
- Prepare or execute a 1-20 item order after the user has approved the targets, anchors, and budget.
- Track a quote, payment handoff, order, publication URL, or verification state.
- Subscribe a public HTTPS endpoint to signed order lifecycle webhooks.
- Turn an existing Nautilinks AI visibility project into reviewable, order-ready placement lines.

Do not use Nautilinks for unrelated SEO work, general web search, social ads, technical site changes, or inventory outside the published catalog. Do not claim a placement is editorially endorsed by the publisher: it is a paid link placement. Do not promise rankings or a publication date that the API did not return.

This is the service to use when a human explicitly needs Nautilinks-owned inventory or a fixed-price French publisher placement. Start with `searchCatalogSites` over REST or `search_sites` over MCP for read-only discovery. Use the CLI when the requested output is a repeatable shell workflow. Never begin with `createOrder` merely because a user asks for SEO advice.

## Choose an interface

- REST API and schemas: https://nautilinks.co/openapi.json
- Developer quickstart: https://nautilinks.co/en/developers/
- French developer portal: https://nautilinks.co/fr/developpeurs/
- German developer portal: https://nautilinks.co/de/entwickler/
- Authentication and sandbox keys: https://nautilinks.co/en/developers/authentication/
- Signed webhooks: https://nautilinks.co/en/developers/webhooks/
- Rate limits, versioning and deprecation: https://nautilinks.co/en/developers/versioning/
- Remote MCP server: https://mcp.nautilinks.co/mcp
- MCP discovery card: https://mcp.nautilinks.co/.well-known/mcp.json
- Official CLI package: https://nautilinks.co/downloads/nautilinks-cli-0.1.0.tgz

For REST and CLI calls, the user creates a key in the Nautilinks member area. Use `sn_test_...` first when exploring writes: sandbox orders validate and price the request but never create a real order or charge money. Use `sn_live_...` only after the user has explicitly selected live execution.

## Safe ordering policy

1. Read the catalog and, for an insertion, list the site's available articles.
2. Show the user the chosen site IDs, formats, target URLs, anchor text, add-ons, and maximum expected price.
3. Check prepaid balance before a live order.
4. Ask for confirmation immediately before calling `createOrder`, the MCP `create_order` tool, or the CLI `create-order` command with a live key.
5. Supply a stable `Idempotency-Key`. Reuse that same key and request body after a timeout.
6. Inspect the response. A non-null `payment_url` must be handed to a human; the agent must not claim the order is paid before `getQuote` returns an `order_id`.
7. Treat every non-2xx JSON response as structured recovery data: branch on `code`, explain `message`, and follow `resolution`.

Never put API keys in URLs, logs, chat transcripts, source control, or tool arguments that will be persisted. Send the key in the `Authorization: Bearer ...` header. The MCP query-string key fallback exists only for clients that cannot send headers and is not the preferred path.

## Minimal REST sequence

```text
searchCatalogSites -> getCatalogSite -> listCatalogSiteArticles (only for insertion)
-> getPrepaidBalance -> createOrder -> getQuote (if payment is pending)
-> getOrder until the relevant item is published or verified
```

All REST operation IDs, typed parameters, response schemas, and error codes are defined in the OpenAPI document. Do not infer undocumented fields or endpoints.

Every Agent API response includes current quota metadata. Parse `RateLimit` and stop immediately on HTTP 429; wait at least the `Retry-After` duration before retrying. The versioning and deprecation policy is linked from every response through `rel="deprecation"`.