Skip to content

API Overview

The Corgi Recommender Service provides a comprehensive REST API for integrating personalized recommendations into Mastodon and Fediverse applications. This reference guide covers the API's design principles, authentication requirements, and available endpoints.

Design Principles

RESTful Architecture

The Corgi API follows REST principles, providing predictable resource-oriented URLs and leveraging standard HTTP methods:

  • GET - Retrieve resources
  • POST - Create new resources
  • PUT - Update existing resources
  • DELETE - Remove resources

Consistent Response Format

All API responses follow a consistent JSON structure:

{
  "data": { /* Resource data */ },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2024-01-20T15:30:45.123Z"
  }
}

Error responses include detailed information:

{
  "error": "Resource not found",
  "message": "Post with ID 'post_12345' does not exist",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "status_code": 404
}

Mastodon Compatibility

The API returns data in Mastodon-compatible formats where applicable, enabling seamless integration with existing Fediverse clients and tools.

Authentication

Bearer Token Authentication

The Corgi API uses OAuth 2.0 Bearer tokens for authentication. Include your access token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Required Headers

For Mastodon integration, include the instance URL:

Authorization: Bearer YOUR_ACCESS_TOKEN
X-Mastodon-Instance: mastodon.social

Example Authenticated Request

curl -X GET https://api.corgi.example/api/v1/recommendations \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "X-Mastodon-Instance: mastodon.social" \
  -H "Content-Type: application/json"

Token Management

Tokens are obtained through the OAuth flow:

  1. Authorization: Direct user to /api/v1/oauth/authorize
  2. Token Exchange: Exchange authorization code for access token
  3. Token Refresh: Use refresh tokens to obtain new access tokens
  4. Token Expiration: Tokens expire after 24 hours by default

Versioning

Current Version

The current API version is v1, accessible at:

https://api.corgi.example/api/v1/

Version Strategy

  • API versions are included in the URL path
  • Major versions introduce breaking changes
  • Minor updates maintain backward compatibility
  • Deprecated endpoints are maintained for at least 6 months

Version Headers

The API version is included in response headers:

X-Service-Version: 1.0.0
X-API-Version: v1

Rate Limiting

Default Limits

Rate limits vary by endpoint and authentication status:

User Type Requests/Minute Requests/Hour
Anonymous 20 1,000
Authenticated 60 2,000
Premium 120 5,000

Endpoint-Specific Limits

Some endpoints have stricter limits due to computational cost:

  • RAG Queries: 10/minute, 100/hour
  • Recommendation Generation: 30/minute, 500/hour
  • Analytics: 20/minute, 200/hour

Rate Limit Headers

Rate limit information is included in response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1617981600

Rate Limit Exceeded

When limits are exceeded, the API returns a 429 status:

{
  "error": "Rate limit exceeded",
  "retry_after": 30,
  "status_code": 429
}

Error Handling

HTTP Status Codes

The API uses standard HTTP status codes:

Code Meaning Description
200 OK Request succeeded
201 Created Resource created successfully
400 Bad Request Invalid request parameters
401 Unauthorized Missing or invalid authentication
403 Forbidden Insufficient permissions
404 Not Found Resource does not exist
429 Too Many Requests Rate limit exceeded
500 Server Error Internal server error
503 Service Unavailable Service temporarily offline

Error Response Format

All errors include structured information:

{
  "error": "Validation error",
  "message": "The 'limit' parameter must be between 1 and 100",
  "field": "limit",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "status_code": 400
}

Common Error Scenarios

Invalid Parameters 

{
  "error": "Invalid parameter",
  "message": "Unknown action_type: 'like'. Valid values are: favorite, bookmark, reblog",
  "field": "action_type",
  "status_code": 400
}

Authentication Failed 

{
  "error": "Authentication required",
  "message": "Please provide valid API key or Bearer token",
  "status_code": 401
}

Request Headers

Required Headers

Header Description Example
Content-Type Media type of request body application/json
Authorization Bearer token for authentication Bearer eyJhbGc...

Optional Headers

Header Description Example
X-Request-ID Client-provided request ID for tracing 550e8400-e29b...
X-Mastodon-Instance Source Mastodon instance mastodon.social
Accept-Language Preferred response language en-US

Response Headers

Standard Headers

All responses include these headers:

Header Description Example
X-Request-ID Request identifier for debugging 550e8400-e29b...
X-Process-Time Server processing time in seconds 0.123456
X-Service-Version API service version 1.0.0

Security Headers

Production responses include security headers:

X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
Content-Security-Policy: default-src 'self'

Endpoint Summary

The Corgi API is organized into logical endpoint categories:

Category Base Path Description Documentation
Interactions /api/v1/interactions Log and retrieve user interactions Interactions API →
Recommendations /api/v1/recommendations Get personalized post recommendations Recommendations API →
Timelines /api/v1/timelines Mastodon-compatible timeline endpoints Timelines API →
Posts /api/v1/posts Manage and retrieve posts Posts API →
Privacy /api/v1/privacy User privacy settings and controls Privacy API →
Analytics /api/v1/analytics Usage analytics and insights Analytics API →
OAuth /api/v1/oauth Authentication and authorization OAuth API →
Health /health, /api/v1/health Service health monitoring Health API →
Proxy /api/v1/proxy Transparent Mastodon proxy Proxy API →
RAG /api/v1/rag AI-powered query system RAG API →
Settings /api/v1/settings User and integration settings Settings API →

Quick Start Example

Here's a complete example of getting personalized recommendations:

import requests

# Configuration
API_BASE = "https://api.corgi.example"
ACCESS_TOKEN = "your_access_token_here"

# Set up headers
headers = {
    "Authorization": f"Bearer {ACCESS_TOKEN}",
    "X-Mastodon-Instance": "mastodon.social",
    "Content-Type": "application/json"
}

# Get recommendations
response = requests.get(
    f"{API_BASE}/api/v1/recommendations",
    headers=headers,
    params={"limit": 10}
)

if response.status_code == 200:
    recommendations = response.json()
    for post in recommendations["recommendations"]:
        print(f"- {post['content'][:100]}...")
        print(f"  Score: {post['ranking_score']}")
        print(f"  Reason: {post['recommendation_reason']}")
else:
    print(f"Error: {response.status_code}")
    print(response.json())

SDK Support

Official SDKs are available for popular languages:

  • Python: pip install corgi-recommender
  • JavaScript/Node.js: npm install @corgi/recommender
  • Ruby: gem install corgi-recommender
  • Go: go get github.com/corgi/recommender-go

API Playground

Explore the API interactively:

Support