For AI Agents & LLMs

This blog is designed to be easily accessible by AI agents, automation tools, and LLMs. This page provides complete instructions for discovering, accessing, and managing content.

Quick Start

The fastest way to access blog content is through our dedicated agent endpoint: 

GET https://ricardas.co.uk/api/agent/posts

This returns a list of all published posts with metadata and direct links to full content.

Discovery Files

Multiple standard discovery formats are available:

  • /ai.txt - Structured AI agent discovery file
  • /.well-known/ai-plugin.json - AI plugin manifest
  • /openapi.json - Complete OpenAPI 3.0 specification
  • /rss.xml - RSS 2.0 feed
  • /feed.json - JSON Feed 1.1 format
  • /sitemap-index.xml - XML sitemap
  • /robots.txt - Crawler directives

API Endpoints

Content Discovery (Public - No Auth)

GET /api/agent/posts

List all published posts with metadata

{
  "posts": [
    {
      "title": "Post Title",
      "slug": "post-slug",
      "description": "Brief description",
      "keywords": ["tag1", "tag2"],
      "published_at": "2024-01-01T00:00:00Z",
      "url": "https://ricardas.co.uk/blog/post-slug",
      "content_url": "https://ricardas.co.uk/api/agent/posts?slug=post-slug"
    }
  ],
  "total": 10
}
GET /api/agent/posts?slug=post-slug

Get full content of a specific post

{
  "post": {
    "title": "Post Title",
    "slug": "post-slug",
    "description": "Brief description",
    "keywords": ["tag1", "tag2"],
    "content": "Full markdown content...",
    "published_at": "2024-01-01T00:00:00Z",
    "author": {
      "name": "Author Name",
      "email": "author@example.com",
      "bio": "Author bio"
    },
    "url": "https://ricardas.co.uk/blog/post-slug"
  }
}
GET /api/search?q=query

Full-text search across posts

GET /api/posts/by-tag/tag-name

Filter posts by tag or keyword

GET /api/meta

Get blog metadata, statistics, and available tags

Usage Examples

Example 1: Discover All Posts

curl https://ricardas.co.uk/api/agent/posts

Example 2: Get Specific Post Content

curl https://ricardas.co.uk/api/agent/posts?slug=my-post

Example 3: Search for Content

curl "https://ricardas.co.uk/api/search?q=AI&limit=5"

Content Structure

Each blog post includes the following fields:

  • title - Post title
  • slug - URL-friendly identifier
  • description - Brief summary
  • keywords - Array of tags/topics
  • markdown_content - Full markdown content
  • status - "draft" or "published"
  • published_at - Publication timestamp
  • author - Author information (name, email, bio, social links)
  • og_image, hero_image - Associated images

Markdown Features

This blog supports standard markdown plus custom components:

  • YouTube embeds: [youtube:VIDEO_ID]
  • Callout boxes: [callout:info]text[/callout]
  • Callout types: info, warning, success
  • Auto-generated slugs from titles
  • Sanitized HTML output for security

Usage Guidelines

Rate Limiting

Please limit requests to a reasonable rate (maximum 60 requests per minute per IP). Excessive traffic may be rate limited.

Caching

API responses include cache headers. Please respect them to reduce load on the server. Cache responses locally when appropriate.

User Agent

Include a descriptive User-Agent header identifying your agent: 

User-Agent: MyAgentName/1.0 (contact@example.com)

Attribution

When using content from this blog:

  • Always attribute to the original author
  • Link back to the original post URL
  • Follow fair use guidelines
  • Do not republish full content without permission

Response Formats

All API endpoints return JSON with the following structure:

Success Response

{
  "post": { ... }  // or "posts": [ ... ]
}

Error Response

{
  "error": "Error message description"
}

HTTP status codes:

  • 200 - Success
  • 400 - Bad Request (invalid input)
  • 404 - Not Found
  • 500 - Internal Server Error

Additional Resources

Support

For questions, issues, or feature requests related to agent access, check the API documentation or examine the OpenAPI specification for complete endpoint details.