Milkey Documentation

API Guide

Integrate Milkey directly into your custom agents or scripts using our programmatic REST interface.

Milkey's core functionality is accessible via a resilient REST API, which is what the official MCP server uses under the hood. You can interface directly if you are writing custom LLM loops or building internal tools.

Base URL

All production requests must be made over HTTPS to:

CODE

https://api.milkey.dev

Authentication

Send your API key as a Bearer token in the Authorization header, and ensure the Content-Type is set correctly for POST/PATCH verbs.

Response Envelope

Milkey returns a consistent JSON envelope for both success and error responses:

JSON

{
  "success": true,
  "data": {},
  "error": null
}

Endpoints

List Catalog Skills

GET /skills

Returns the authenticated user plan, total available skills, and per-skill enabled state.

JSON

{
  "success": true,
  "data": {
    "plan": "free",
    "total": 2,
    "skills": [
      {
        "id": "clx123",
        "name": "React Best Practices",
        "slug": "react-best-practices",
        "description": "Production-ready React patterns.",
        "source": null,
        "category": "development-technical",
        "trustScore": 8,
        "isPremium": false,
        "version": 1,
        "updatedAt": "2026-03-03T00:00:00.000Z",
        "isEnabled": true
      }
    ]
  },
  "error": null
}

List Enabled Skills

GET /user/skills

Returns only the skills currently enabled for the authenticated account.

JSON

{
  "success": true,
  "data": {
    "total": 1,
    "skills": [
      {
        "id": "clx123",
        "name": "React Best Practices",
        "slug": "react-best-practices",
        "description": "Production-ready React patterns.",
        "source": null,
        "category": "development-technical",
        "trustScore": 8,
        "isPremium": false,
        "version": 1,
        "updatedAt": "2026-03-03T00:00:00.000Z"
      }
    ]
  },
  "error": null
}

Get Skill Content

GET /skills/:slug

Returns the full skill payload, including content and current enabled state.

JSON

{
  "success": true,
  "data": {
    "skill": {
      "id": "clx123",
      "name": "React Best Practices",
      "slug": "react-best-practices",
      "description": "Production-ready React patterns.",
      "source": null,
      "category": "development-technical",
      "trustScore": 8,
      "content": "# React Best Practices\n...",
      "isActive": true,
      "isPremium": false,
      "version": 1,
      "updatedAt": "2026-03-03T00:00:00.000Z",
      "isEnabled": true
    }
  },
  "error": null
}

Error Handling

Milkey returns standard HTTP status codes regarding request success or failure. The response body will contain a standardized JSON envelope explaining the issue.

400 Bad Request: Missing or invalid parameters.
401 Unauthorized: Token is missing or invalid.
429 Too Many Requests: Usage quota exceeded.
404 Not Found: Skill doesn't exist or isn't enabled.

Implement retry/backoff and alerting for 429 responses so automated agents fail gracefully when limits are reached.