# designpattern.fyi Developer API & MCP Server Documentation

> Official designpattern.fyi developer resources: OpenAPI 3.1.0 specification, REST API endpoints, Model Context Protocol (MCP) server schemas, JSON data feeds, and AI agent integration guides.

- **Category**: 

- **Canonical URL**: https://designpattern.fyi/developers/

---

## Description
Official designpattern.fyi developer resources: OpenAPI 3.1.0 specification, REST API endpoints, Model Context Protocol (MCP) server schemas, JSON data feeds, and AI agent integration guides.








## Additional Notes

# designpattern.fyi Developer Resources

Welcome to the official designpattern.fyi developer hub. This page provides comprehensive access to all machine-readable APIs, OpenAPI specifications, Model Context Protocol (MCP) server schemas, and integration resources for developers and AI agents.

## Quick Links

- **[OpenAPI 3.1.0 Specification](/api/openapi.json)** - Complete API documentation with all endpoints
- **[Patterns Catalog API](/api/v1/patterns.json)** - All 758+ software design patterns in JSON
- **[Categories API](/api/v1/categories.json)** - Category taxonomies and subcategory metadata
- **[Skills API](/api/v1/skills.json)** - AI agent skill specifications for autonomous systems
- **[MCP Schema](/api/v1/mcp-schema.json)** - Model Context Protocol (MCP) server tool definitions
- **[Agent Manifest](/agent-manifest.json)** - Service discovery and integration manifest for AI agents
- **[llms.txt](/llms.txt)** - Standard LLM guidance and agent instruction index
- **[Agent Instructions](/agent-instructions.txt)** - Specific AI agent integration guidance

## API Endpoints

### Core Data APIs

|| Endpoint | Description | Format |
||----------|-------------|--------|
|| `/api/v1/patterns.json` | Complete catalog of 758+ software design patterns | JSON |
|| `/api/v1/categories.json` | All category taxonomies and subcategory metadata | JSON |
|| `/api/v1/skills.json` | AI agent skill specifications | JSON |
|| `/api/v1/mcp-schema.json` | Model Context Protocol tool schema | JSON |
|| `/api/v1/error.json` | Canonical error response schema | JSON |

### Documentation & Integration

|| Endpoint | Description | Format |
||----------|-------------|--------|
|| `/api/openapi.json` | OpenAPI 3.1.0 specification | JSON |
|| `/agent-manifest.json` | Service discovery and integration manifest for AI agents | JSON |
|| `/llms.txt` | Standard LLM guidance index | Plain text |
|| `/agent-instructions.txt` | AI agent integration instructions | Plain text |
|| `/AGENTS.md` | Agent calling guidelines | Markdown |

## Agent Manifest

The **[Agent Manifest](/agent-manifest.json)** provides a comprehensive service discovery document for AI agents, including:

- Service capabilities and compatibility information
- Complete endpoint listing with rate limits and examples
- Protocol support (HTTP, MCP, OpenAPI)
- Content categories and pattern counts
- Integration examples in multiple languages
- Rate limiting and support information

### Using the Agent Manifest

```bash
# Fetch the agent manifest
curl https://www.designpattern.fyi/agent-manifest.json

# Parse for service capabilities
jq '.capabilities' agent-manifest.json

# Get API endpoints with rate limits
jq '.endpoints.api.endpoints' agent-manifest.json
```

## API Features

### Machine-Readable Error Responses
All API errors return structured JSON with error codes, messages, and resolution hints:
```json
{
  "error": {
    "status": 404,
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested API resource does not exist on designpattern.fyi.",
    "docs": "https://www.designpattern.fyi/developers/",
    "openapi_spec": "https://www.designpattern.fyi/api/openapi.json"
  },
  "resolution": {
    "description": "Use one of the following valid API endpoints.",
    "valid_endpoints": [...],
    "discovery": {...}
  }
}
```

### Rate Limiting Headers
API responses include standard rate limit headers for agent self-throttling:
- `RateLimit-Limit`: 1000 requests per hour
- `RateLimit-Remaining`: Remaining requests in current window
- `RateLimit-Reset`: Unix timestamp when window resets
- `RateLimit-Window`: Window duration in seconds (3600)
- `Retry-After`: Seconds to wait before retry (on 429 responses)

### Content Negotiation
Support for acceptmarkdown.com content negotiation:
- Set `Accept: text/markdown` header to receive Markdown representations
- `Vary: Accept, Accept-Encoding` headers ensure proper CDN caching

## Agent Integration

designpattern.fyi is optimized for AI agent integration with:

- **Structured JSON responses** with proper error handling
- **Machine-readable error schemas** for agent recovery
- **Comprehensive OpenAPI specification** for automatic client generation
- **Standard llms.txt compliance** for LLM guidance
- **MCP server schemas** for Claude/Cursor tool calling
- **Agent-friendly 404 responses** with recovery guidance
- **Service discovery manifest** for automated integration

## Integration Examples

### Python Example
```python
import requests

# Fetch patterns catalog
response = requests.get('https://www.designpattern.fyi/api/v1/patterns.json')
patterns = response.json()

# Check rate limits
rate_limit = response.headers.get('RateLimit-Limit')
rate_remaining = response.headers.get('RateLimit-Remaining')
```

### cURL Example
```bash
# Fetch with rate limit headers
curl -I https://www.designpattern.fyi/api/v1/patterns.json

# Request Markdown content negotiation
curl -H "Accept: text/markdown" https://www.designpattern.fyi/
```

## Error Handling

All API errors follow the structured JSON format defined in `/api/v1/error.json`. Agents should:
1. Parse the `error.code` field for machine-readable error identification
2. Follow `resolution.valid_endpoints` for correct API usage
3. Use `resolution.discovery` links for site navigation
4. Respect `Retry-After` headers on rate limit errors

## Support & Documentation

- **OpenAPI Specification**: Full API documentation in OpenAPI 3.1.0 format
- **Agent Manifest**: Service discovery and integration guide at `/agent-manifest.json`
- **Error Schema**: Canonical error response format at `/api/v1/error.json`
- **Agent Guidelines**: Complete agent integration instructions in `/agent-instructions.txt`
- **Developer Hub**: This page for ongoing updates and integration guides