# mikrouli -- LLM / agent integration guide

mikrouli is a URL-shortening service with click analytics.
This file describes how automated agents and scripts can interact with it.

## API base

Base URL: https://mikrou.li
API prefix: /api


## Step 1: Get an API key

All write endpoints and the MCP server require an API key with the mk_ prefix.
The full secret is shown once at creation time only.

To obtain a key:
  1. Sign in to your account at https://mikrou.li
  2. Open the API Keys page from the account menu
  3. Create a new key and copy the mk_... value

Every subsequent machine-to-machine call authenticates with the header:

  x-api-key: mk_<your-key>

Key format: mk_<random>   (e.g. mk_a1b2c3d4...)

A missing or invalid key returns 401 with:
  { "status": 401, "title": "Unauthorized", "type": "..." }


## REST: create a short link

Endpoint: POST /api/urls
Content-Type: application/json

Request body:
  { "url": "https://example.com/your-long-url" }

Example (copy-pasteable):

  curl -s -X POST https://mikrou.li/api/urls \
    -H "Content-Type: application/json" \
    -H "x-api-key: mk_<your-key>" \
    -d '{"url":"https://example.com/your-long-url"}' | jq .

Response (201 Created) -- PublicLink shape:
  {
    "shortUrl": "abc123",
    "originalUrl": "https://example.com/your-long-url",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "expiresAt": null
  }

IMPORTANT: "shortUrl" is a 6-character alphanumeric slug, NOT a full URL.
There is no "slug" field; the field is named "shortUrl".
To build the shareable link, prepend the base URL:
  shareable link = https://mikrou.li + "/" + shortUrl
  example: https://mikrou.li/abc123

Error responses follow RFC 9457 application/problem+json.


## MCP server (Streamable HTTP)

mikrouli exposes a hosted Model Context Protocol server.

Endpoint: POST /api/mcp
Protocol: Streamable HTTP (MCP 2024-11-05)
Auth: x-api-key header (same mk_ key as REST)
Required header: Accept: application/json, text/event-stream
  (Streamable HTTP requires it; MCP client harnesses send it automatically.)

Available tool: create_short_link
  Input:  { "url": "https://example.com/long-url" }
  Output text: the full usable link, e.g. "https://mikrou.li/abc123"
  structuredContent fields:
    shortUrl    -- 6-character slug (PublicLink contract, same as REST)
    shortLink   -- full usable link: base URL + "/" + shortUrl
    originalUrl -- the URL that was shortened
    createdAt   -- ISO 8601 timestamp
    expiresAt   -- ISO 8601 timestamp or null

Example initialization call:

  curl -s -X POST https://mikrou.li/api/mcp \
    -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" \
    -H "x-api-key: mk_<your-key>" \
    -d '{
      "jsonrpc": "2.0",
      "method": "initialize",
      "id": 1,
      "params": {
        "protocolVersion": "2024-11-05",
        "capabilities": {},
        "clientInfo": { "name": "my-agent", "version": "1" }
      }
    }'

To connect an MCP-aware harness, point it at:
  URL:    https://mikrou.li/api/mcp
  Header: x-api-key: mk_<your-key>


## Add to Claude Code

Run this command once to register mikrouli as an MCP server in Claude Code:

  claude mcp add --scope user --transport http mikrouli \
    https://mikrou.li/api/mcp \
    --header "x-api-key: mk_<your-key>"

Flags:
  --scope user       persists the server across all your projects
  --transport http   uses Streamable HTTP (required for hosted MCP servers)
  --header           threads the API key into every request


## Summary

| Path         | Method | Auth needed | Purpose                |
|--------------|--------|-------------|------------------------|
| /api/urls    | POST   | x-api-key   | Create a short link    |
| /api/urls    | GET    | x-api-key   | List your links        |
| /api/mcp     | POST   | x-api-key   | MCP Streamable HTTP    |
| /api/api-keys| POST   | cookie      | Mint a new mk_ key     |