docs: improve agent API guidance and no-key operation discoverability

docs/api/agent-playbook.md

@@ -0,0 +1,73 @@
+---
+id: agent-playbook
+title: AI Agent API Playbook
+slug: /api/agent-playbook
+---
+
+# AI Agent API Playbook
+
+Use this playbook when an AI agent interacts with the Blink GraphQL API.
+
+## Core Rule
+
+If anything is unclear, incomplete, or ambiguous, the agent must check the API reference before generating a final answer or request payload.
+
+## Required Order of Operations
+
+1. Identify the user intent (for example: create invoice, send payment, check wallet balance).
+2. Find the exact operation in the public API reference.
+3. Validate all field names and input object names against the reference.
+4. Validate required authentication and required scopes.
+5. Validate response unions and error shapes.
+6. Only then generate the GraphQL operation and example code.
+
+## Canonical Sources
+
+Use these sources in this order:
+
+1. LLM-friendly schema JSON (preferred): [/reference/graphql-api-for-llm.json](/reference/graphql-api-for-llm.json)
+2. OpenAPI JSON (alternative): [/reference/graphql-openapi.json](/reference/graphql-openapi.json)
+3. Public HTML API reference: [https://dev.blink.sv/public-api-reference.html](https://dev.blink.sv/public-api-reference.html)
+4. No-key operations guide: [/api/no-api-key-operations](/api/no-api-key-operations)
+5. Authentication guide: [/api/auth](/api/auth)
+6. Error handling guide: [/api/errors](/api/errors)
+
+## Safety and Accuracy Constraints
+
+- Never invent mutations, fields, arguments, or enum values.
+- Never assume authentication is optional unless the docs explicitly say so.
+- Always include `X-API-KEY` for authenticated requests.
+- Prefer minimal, valid GraphQL examples over broad speculative examples.
+- If the docs and memory conflict, trust the docs.
+
+## Fallback Behavior for Unclear Requests
+
+When the user request is missing details, ask a short clarification question.
+If authentication requirements are unclear, check [No API Key Operations](/api/no-api-key-operations) and then verify the exact operation in the public API reference.
+
+Examples:
+
+- "Should this be BTC or USD wallet flow?"
+- "Do you want mainnet (`api.blink.sv`) or staging (`api.staging.blink.sv`)?"
+- "Do you want a receive flow (invoice/address) or send flow (payment/payout)?"
+
+## Environment Endpoints
+
+- Production GraphQL: `https://api.blink.sv/graphql`
+- Staging GraphQL: `https://api.staging.blink.sv/graphql`
+
+## Minimal Verification Checklist
+
+Before returning a final API answer, verify:
+
+- Operation exists in reference
+- Input types and required fields match reference
+- Example includes correct auth header if required
+- Response handling includes `errors` path and GraphQL error semantics
+
+## Related Reading
+
+- [GraphQL Intro](/api/graphql-intro)
+- [Authentication](/api/auth)
+- [Error Handling](/api/errors)
+- [Pagination](/api/pagination)

docs/api/auth.mdx

@@ -35,6 +35,8 @@ Use the same credentials as with the [Blink wallet app](https://get.blink.sv)
 
 ## API Authentication
 
+Need an unauthenticated flow? Start with [No API Key Operations](/api/no-api-key-operations), then confirm the exact operation in the [Public API Reference](https://dev.blink.sv/public-api-reference.html).
+
 :::warning Security Best Practices
 Never expose your API keys in client-side code (like frontend JavaScript) where they can be extracted by users. API keys should only be used in server-side applications where they remain private.
 

docs/api/llm-api-reference.md

@@ -35,6 +35,8 @@ For systems that work better with OpenAPI specifications:
 
 ## How to Use with LLM Agents
 
+Before generating API calls, follow the [AI Agent API Playbook](/api/agent-playbook). In particular: if anything is unclear, verify it against the machine-readable reference first.
+
 Here are some examples of how to use these formats with popular LLM frameworks:
 
 ### Using with LangChain
@@ -131,6 +133,8 @@ The API reference files are automatically updated when the GraphQL schema change
 
 ## Additional Resources
 
+- [No API Key Operations](/api/no-api-key-operations) - Fast path for unauthenticated query/mutation discovery
+- [AI Agent API Playbook](/api/agent-playbook) - Required workflow for reliable agent behavior
 - [GraphQL Introduction](/api/graphql-intro) - Learn the basics of our GraphQL API
 - [Authentication](/api/auth) - How to authenticate with the Blink API
 - [Postman Collection](/api/postman) - Test the API interactively

docs/api/no-api-key-operations.md

@@ -0,0 +1,48 @@
+---
+id: no-api-key-operations
+title: No API Key Operations
+slug: /api/no-api-key-operations
+---
+
+# No API Key Operations
+
+This page highlights public GraphQL operations commonly used without an API key.
+
+:::note
+This list is intended for quick discovery.
+Always verify the latest behavior in the public API reference before shipping production code.
+:::
+
+## Mutations commonly used without `X-API-KEY`
+
+These are the no-key mutations commonly used in login and invoice-on-behalf flows:
+
+- [`lnInvoiceCreateOnBehalfOfRecipient`](https://dev.blink.sv/public-api-reference.html#mutation-lnInvoiceCreateOnBehalfOfRecipient)
+- [`lnNoAmountInvoiceCreateOnBehalfOfRecipient`](https://dev.blink.sv/public-api-reference.html#mutation-lnNoAmountInvoiceCreateOnBehalfOfRecipient)
+- [`lnUsdInvoiceCreateOnBehalfOfRecipient`](https://dev.blink.sv/public-api-reference.html#mutation-lnUsdInvoiceCreateOnBehalfOfRecipient)
+- [`lnUsdInvoiceBtcDenominatedCreateOnBehalfOfRecipient`](https://dev.blink.sv/public-api-reference.html#mutation-lnUsdInvoiceBtcDenominatedCreateOnBehalfOfRecipient)
+
+## Queries commonly used without `X-API-KEY`
+
+- [`accountDefaultWallet`](https://dev.blink.sv/public-api-reference.html#query-accountDefaultWallet)
+- [`lnInvoicePaymentStatusByPaymentRequest`](https://dev.blink.sv/public-api-reference.html#query-lnInvoicePaymentStatusByPaymentRequest)
+- [`lnInvoicePaymentStatusByHash`](https://dev.blink.sv/public-api-reference.html#query-lnInvoicePaymentStatusByHash) (legacy, prefer `lnInvoicePaymentStatusByPaymentRequest`)
+- [`btcPriceList`](https://dev.blink.sv/public-api-reference.html#query-btcPriceList)
+- [`businessMapMarkers`](https://dev.blink.sv/public-api-reference.html#query-businessMapMarkers)
+
+## Agent Rule
+
+When an agent needs an unauthenticated flow:
+
+1. Start from this page.
+2. Open the exact operation in the public API reference.
+3. Confirm the required input object and response shape.
+4. If anything is unclear, check `/reference/graphql-api-for-llm.json` before generating code.
+5. If the operation needs auth after all, retry with `X-API-KEY` and the minimum required scope.
+
+## Related Docs
+
+- [Authentication](/api/auth)
+- [API Reference for LLMs](/api/llm-api-reference)
+- [AI Agent API Playbook](/api/agent-playbook)
+- [Public API Reference](https://dev.blink.sv/public-api-reference.html)

sidebars.js

@@ -31,6 +31,7 @@ const sidebars = {
   apiSidebar: [
     'intro',
     'api/auth',
+    'api/no-api-key-operations',
     {
       type: 'category',
       label: 'API tutorials',
@@ -93,6 +94,7 @@ const sidebars = {
         'api/oauth2',
         'api/proof-of-payment',
         'api/errors',
+        'api/agent-playbook',
         'api/postman',
         'api/llm-api-reference',
         {

static/llms.txt

@@ -0,0 +1,25 @@
+# Blink API docs for AI agents
+
+This file helps AI agents discover canonical API references and operating rules.
+
+project: Blink Developer Documentation
+base_url: https://dev.blink.sv
+graphql_production: https://api.blink.sv/graphql
+graphql_staging: https://api.staging.blink.sv/graphql
+auth_header: X-API-KEY
+
+priority_sources:
+- https://dev.blink.sv/reference/graphql-api-for-llm.json
+- https://dev.blink.sv/reference/graphql-openapi.json
+- https://dev.blink.sv/public-api-reference.html
+- https://dev.blink.sv/api/no-api-key-operations
+- https://dev.blink.sv/api/agent-playbook
+- https://dev.blink.sv/api/auth
+- https://dev.blink.sv/api/errors
+
+hard_rules:
+- If unclear, consult the API reference before producing an answer.
+- Do not invent GraphQL fields, mutations, arguments, or enums.
+- Validate auth requirements and scope expectations.
+- If auth is unclear, check no-key operations first, then verify exact operation in public reference.
+- Prefer concise, valid examples with explicit environment.