erold.guide
Back to Contribute

Contribution API

Submit guidelines programmatically via our REST API. Perfect for AI agents and automated workflows.

Coming Soon

The contribution API is under development. This documentation describes the planned API. For now, contributions can be submitted via GitHub pull requests.

Base URL

https://contribute.erold.guide

Authentication

All contribution endpoints require authentication via GitHub OAuth. After authenticating, include the JWT token in the Authorization header.

Authorization Header
# Include in all requests
Authorization: Bearer YOUR_JWT_TOKEN

OAuth Flow

  1. 1. Redirect user to /auth/github
  2. 2. User authorizes with GitHub
  3. 3. Callback returns JWT token
  4. 4. Use token in Authorization header

Endpoints

POST /v1/contributions Soon

Submit a new guideline for review

Auth: Required (GitHub OAuth)

GET /v1/contributions/:id Soon

Check the status of a submission

Auth: Required (owner or admin)

GET /v1/contributions Soon

List your submissions

Auth: Required

PUT /v1/contributions/:id Soon

Update a pending submission

Auth: Required (owner)

DELETE /v1/contributions/:id Soon

Withdraw a pending submission

Auth: Required (owner)

Submit a Guideline

POST /v1/contributions 
{
  "framework": "nextjs",
  "category": "performance",
  "guideline": {
    "title": "Use Dynamic Imports for Large Components",
    "slug": "dynamic-imports-large-components",
    "version": "1.0.0",
    "description": "Lazy load large components to reduce initial bundle size...",
    "tags": ["performance", "bundle-size", "code-splitting"],
    "difficulty": "intermediate",
    "estimatedReadTime": 5,
    "content": "# Use Dynamic Imports...\n\nMarkdown content here...",
    "ai": {
      "prompt_snippet": "Use next/dynamic for components over 50KB...",
      "applies_when": ["Adding large charts", "Modal dialogs"],
      "does_not_apply_when": ["Small utility components"],
      "priority": "recommended",
      "confidence": "established"
    }
  }
}

Response

201 Created 
{
  "id": "contrib_abc123",
  "status": "pending",
  "createdAt": "2026-01-01T12:00:00Z",
  "contributor": {
    "github": "your-username",
    "avatar": "https://github.com/your-username.png"
  },
  "framework": "nextjs",
  "category": "performance",
  "guideline": { ... },
  "review": null
}

Submission Statuses

pending

Submitted, awaiting AI review

ai_approved

Passed AI review, awaiting human review

ai_needs_changes

AI found issues, needs revision

approved

Approved and published

rejected

Rejected by reviewer

withdrawn

Withdrawn by contributor

Schema Reference

Guidelines must conform to our schema. Here are the required and optional fields:

Field Type Required Description
title string Yes 5-100 characters
slug string Yes URL-friendly, lowercase
version string Yes Semver format (1.0.0)
description string Yes 20-300 characters
tags string[] Yes 1-10 tags
difficulty enum Yes beginner, intermediate, advanced
content string Yes Markdown content
ai object Recommended AI optimization fields
minVersion string No Min framework version
prerequisites string[] No Slugs of required guidelines

For the complete schema, see the Style Guide.

Rate Limits

Submissions per hour 10
Submissions per day 50
Pending submissions 20 max

Error Responses

Error Format 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid guideline format",
    "details": [
      { "field": "title", "message": "Must be 5-100 characters" },
      { "field": "tags", "message": "At least 1 tag required" }
    ]
  }
}
400 Validation error - check details array
401 Missing or invalid authentication
409 Duplicate guideline (slug exists)
429 Rate limit exceeded

Ready to Contribute?

While the API is in development, you can contribute via GitHub pull requests.

Open on GitHub