diff --git a/docs/api/agent-playbook.md b/docs/api/agent-playbook.md index c71e507..092eb10 100644 --- a/docs/api/agent-playbook.md +++ b/docs/api/agent-playbook.md @@ -21,6 +21,10 @@ If anything is unclear, incomplete, or ambiguous, the agent must check the API r 5. Validate response unions and error shapes. 6. Only then generate the GraphQL operation and example code. +## Discovery + +Start here: [https://dev.blink.sv/llms.txt](https://dev.blink.sv/llms.txt) — structured metadata with endpoints, source URLs, and hard rules. + ## Canonical Sources Use these sources in this order: @@ -71,3 +75,4 @@ Before returning a final API answer, verify: - [Authentication](/api/auth) - [Error Handling](/api/errors) - [Pagination](/api/pagination) +- [Building with AI Agents](/api/llm-api-reference) - Schema downloads and integration examples for developers diff --git a/docs/api/llm-api-reference.md b/docs/api/llm-api-reference.md index 98c404f..b722122 100644 --- a/docs/api/llm-api-reference.md +++ b/docs/api/llm-api-reference.md @@ -1,140 +1,115 @@ --- id: llm-api-reference -title: API Reference for LLMs +title: Building with AI Agents slug: /api/llm-api-reference --- -# GraphQL API Reference for LLM Agents +# Building with AI Agents -This page provides access to machine-readable formats of the Blink GraphQL API schema, specifically designed for consumption by Large Language Models (LLMs) and AI agents. +This guide is for **developers** who want to integrate AI agents or LLMs with the Blink API. It covers agent discovery, the machine-readable schema formats you can feed to your agent, and practical integration patterns. -## Why Use Machine-Readable API References? +:::tip For AI agents +If you are an AI agent, skip this page and follow the [AI Agent API Playbook](/api/agent-playbook) directly. +::: -When building applications that use AI agents or LLMs to interact with the Blink API, providing structured API documentation in formats that are optimized for machine consumption offers several advantages: +## Agent Discovery with llms.txt -1. **Improved Understanding**: LLMs can better understand the API structure, available operations, and data types -2. **More Accurate Code Generation**: AI agents can generate more accurate API calls with proper parameters -3. **Better Error Handling**: Understanding the API schema helps LLMs suggest appropriate error handling strategies -4. **Reduced Hallucinations**: Structured documentation reduces the chance of LLMs "hallucinating" non-existent API features +The site publishes a [`llms.txt`](https://dev.blink.sv/llms.txt) file at the root — a lightweight, structured file that gives any agent the endpoints, canonical source URLs, and hard rules in a single fetch: -## Recommended Formats for LLMs +```bash +curl -s https://dev.blink.sv/llms.txt +``` + +Point your agent at this URL first. It contains everything needed to bootstrap: production/staging GraphQL endpoints, auth header name, prioritized source list, and safety rules. -We provide the following machine-readable formats of the Blink GraphQL API schema, optimized for LLM consumption: +## Machine-Readable Schema Downloads -### Enhanced JSON Schema (Recommended) +We provide the Blink GraphQL API schema in formats optimized for LLM consumption: -This is our recommended format for most LLM applications. It provides a clean, structured representation of the GraphQL schema with additional context: +| Format | Best for | Download | +|--------|----------|----------| +| Enhanced LLM-friendly JSON | Most LLM apps, code generation | graphql-api-for-llm.json | +| OpenAPI specification | Function calling, automated integrations | graphql-openapi.json | -- Download Enhanced LLM-Friendly Schema (JSON) +## Integration Patterns -### OpenAPI Format (Alternative) +### Pattern 1: System prompt + schema (framework-agnostic) -For systems that work better with OpenAPI specifications: +The simplest approach — fetch the schema and playbook, then include them in the system prompt of any LLM: -- Download OpenAPI Specification (JSON) +```bash +# Fetch the schema and playbook once +curl -s https://dev.blink.sv/reference/graphql-api-for-llm.json -o blink-schema.json +curl -s https://dev.blink.sv/api/agent-playbook -o playbook.md +``` -## How to Use with LLM Agents +Then in your system prompt: -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. +``` +You are a Blink API assistant. Follow the playbook rules below strictly. + + +{contents of playbook.md} + + + +{contents of blink-schema.json} + +``` -Here are some examples of how to use these formats with popular LLM frameworks: +This works with any LLM provider — OpenAI, Anthropic, open-source models, etc. -### Using with LangChain +### Pattern 2: Python with httpx ```python -from langchain.agents import Tool -from langchain.agents import initialize_agent -from langchain.llms import OpenAI -import requests +import httpx import json -# Load the API schema -api_schema_url = "https://dev.blink.sv/reference/graphql-api-for-llm.json" -api_schema = json.loads(requests.get(api_schema_url).text) - -# Create a tool that provides the API schema as context -tools = [ - Tool( - name="BlinkAPI", - func=lambda _: "API schema is already provided in your context", - description="Blink GraphQL API schema information" - ) -] - -# Initialize the agent with the API schema in its context -llm = OpenAI(temperature=0) -agent = initialize_agent(tools, llm, agent="zero-shot-react-description", verbose=True) - -# Use the agent with the API schema as context -agent.run( - input="How do I create a lightning invoice using the Blink API?", - context={"api_schema": api_schema} -) +# Fetch schema and playbook at startup +schema = httpx.get("https://dev.blink.sv/reference/graphql-api-for-llm.json").json() +playbook = httpx.get("https://dev.blink.sv/llms.txt").text + +system_prompt = f""" +You are a Blink API assistant. +Follow these rules:\n{playbook} + +API schema:\n{json.dumps(schema, indent=2)} +""" + +# Use with any LLM client +# client.chat(system=system_prompt, messages=[...]) ``` -### Using with OpenAI Assistants +### Pattern 3: Node.js ```javascript -const { OpenAI } = require('openai'); -const fs = require('fs'); -const path = require('path'); - -const openai = new OpenAI({ - apiKey: process.env.OPENAI_API_KEY, -}); - -async function createAssistantWithBlinkAPI() { - // Download the API schema - const response = await fetch('https://dev.blink.sv/reference/graphql-api-for-llm.json'); - const apiSchema = await response.json(); - - // Save it to a file - fs.writeFileSync('blink-api-schema.json', JSON.stringify(apiSchema)); - - // Create an assistant with the API schema as a file - const assistant = await openai.beta.assistants.create({ - name: "Blink API Assistant", - instructions: "You are an assistant that helps users interact with the Blink GraphQL API. Use the provided API schema to answer questions and generate code examples.", - model: "gpt-4-turbo", - tools: [{ type: "code_interpreter" }], - file_ids: [ - // Upload the API schema file to OpenAI and get its file ID - await openai.files.create({ - file: fs.createReadStream(path.resolve('blink-api-schema.json')), - purpose: 'assistants', - }).then(file => file.id) - ] - }); - - console.log("Assistant created with ID:", assistant.id); - return assistant; -} - -createAssistantWithBlinkAPI(); +const schema = await fetch('https://dev.blink.sv/reference/graphql-api-for-llm.json').then(r => r.json()); +const playbook = await fetch('https://dev.blink.sv/llms.txt').then(r => r.text()); + +const systemPrompt = ` +You are a Blink API assistant. +Follow these rules: +${playbook} + +API schema: +${JSON.stringify(schema, null, 2)} +`; + +// Use with any LLM SDK +// e.g. OpenAI, Anthropic, etc. ``` ## Generating Updated Schemas -The API reference files are automatically updated when the GraphQL schema changes. If you need to generate them manually, you can use the following script: +The API reference files are automatically updated when the GraphQL schema changes. To generate them manually: ```bash -# Generate all formats ./scripts/generate-api-reference-combined.sh ``` -## Recommended Format by Use Case - -| Use Case | Recommended Format | -|----------|-------------------| -| Most LLM applications | Enhanced LLM-friendly JSON | -| OpenAI function calling | OpenAPI specification | -| Code generation | Enhanced LLM-friendly JSON | -| Automated API integration | OpenAPI specification | - ## 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 +- [AI Agent API Playbook](/api/agent-playbook) - Concise instruction set consumed directly by AI agents +- [No API Key Operations](/api/no-api-key-operations) - Unauthenticated query/mutation discovery +- [GraphQL Introduction](/api/graphql-intro) - Learn the basics of the GraphQL API - [Authentication](/api/auth) - How to authenticate with the Blink API -- [Postman Collection](/api/postman) - Test the API interactively diff --git a/sidebars.js b/sidebars.js index a843c0d..f472d33 100644 --- a/sidebars.js +++ b/sidebars.js @@ -94,14 +94,14 @@ const sidebars = { 'api/oauth2', 'api/proof-of-payment', 'api/errors', - 'api/agent-playbook', 'api/postman', - 'api/llm-api-reference', { type: 'link', label: 'API reference', href: 'https://dev.blink.sv/public-api-reference.html', }, + 'api/llm-api-reference', + 'api/agent-playbook', ], }, {