REST API

The Smidge REST API lets you generate skills programmatically, check your credit balance, list past generations, and download skill files. It uses the same pipeline as the web app and CLI — same quality, same speed.

Base URL: https://smdg.app/api/v1

Authentication

All API requests require a Bearer token. Generate API keys from your Account page under the API Keys section.

Authorization: Bearer smidge_sk_abc123...

Keys use the smidge_sk_ prefix. Each key is hashed with bcrypt — the full key is shown only once at creation. You can create multiple keys with descriptive names and revoke them individually.

Endpoints

Generate a Skill

POST /api/v1/generate

Accepts multipart/form-data with a source (URL, file upload, or raw text). Returns the generated skill as JSON. Costs 1 credit.

curl -X POST https://smdg.app/api/v1/generate \
  -H "Authorization: Bearer smidge_sk_..." \
  -F "source=https://youtube.com/watch?v=dQw4w9WgXcQ" \
  -F "name=my-skill"

{
  "skill": {
    "id": "uuid",
    "filename": "my-skill.md",
    "content": "---\ntitle: My Skill\n...",
    "reference_files": [],
    "word_count": 1847
  },
  "metadata": {
    "source_type": "youtube",
    "credits_remaining": 4
  }
}

Detect Topics

POST /api/v1/detect-topics

Analyzes your source and returns suggested skill topics. Free — no credits used. If shouldCatalogue is true, present the topics to your user and call /api/v1/generate/catalogue with their selection. Otherwise, call /api/v1/generate directly.

{
  "shouldCatalogue": true,
  "wordCount": 18420,
  "topics": [
    {
      "topicName": "Sales Methodology",
      "slug": "sales-methodology",
      "description": "Core framework for structuring a B2B sales process.",
      "estimatedWordCount": 450
    }
  ]
}

Generate Catalogue

POST /api/v1/generate/catalogue

Generates multiple skills from a source. 1 credit per selected topic — the master index skill is free. Returns a streaming response; results are delivered on completion.

{
  "catalogueId": "uuid",
  "skills": [
    {
      "topic": { "topicName": "Sales Methodology", "slug": "sales-methodology", ... },
      "filename": "sales-methodology.md",
      "content": "---\n...",
      "referenceFiles": [],
      "wordCount": 432
    }
  ],
  "masterIndex": {
    "filename": "index.md",
    "content": "---\n..."
  },
  "creditsRemaining": 2
}

Check Credits

GET /api/v1/credits

curl https://smdg.app/api/v1/credits \
  -H "Authorization: Bearer smidge_sk_..."

{
  "credits_remaining": 12,
  "plan": "credits",
  "credit_packs_purchased": 2,
  "total_generations": 8
}

List Generations

GET /api/v1/generations

Returns your generation history with pagination. Supports limit (default 20, max 100) and offset query params.

curl "https://smdg.app/api/v1/generations?limit=10" \
  -H "Authorization: Bearer smidge_sk_..."

Download a Skill

GET /api/v1/generations/:id/skill

Returns the raw SKILL.md file as text/markdown with a Content-Disposition: attachment header.

curl "https://smdg.app/api/v1/generations/<id>/skill" \
  -H "Authorization: Bearer smidge_sk_..." \
  -o my-skill.md

Error Format

All errors return a consistent JSON shape:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "You need at least 1 credit to generate a skill."
  }
}

Rate Limits

Rate limits are applied per API key using a sliding window. Every response includes headers so you can track your usage:

When rate limited, you'll receive a 429 response with a Retry-After header indicating when to retry.

Managing API Keys

API keys are managed from your Account page in the web app, not via API. You can:

• ●Create multiple keys with descriptive names
• ●See when each key was last used
• ●Revoke individual keys without affecting others