REST API Reference

Base URL

https://api.squillify.com

Every endpoint below is relative to this base. How you authenticate depends on the endpoint you’re hitting — the Authentication docs have the details when you need them.

POST /v1/execute

This is your main endpoint for running a MicroSkill over REST — the one you’ll reach for most often.

Headers

Request body

{
  "skillKey": "text.slugify",
  "input": {
    "text": "Hello World Example"
  },
  "version": "1.0.0"
}

Response (200)

{
  "output": {
    "slug": "hello-world-example"
  },
  "metadata": {
    "skill_key": "text.slugify",
    "latency_ms": 3,
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "executed_at": "2026-06-03T07:21:00Z",
    "version_pinned": false
  }
}

On success, we hand you back your quota headers so you always know where you stand: X-Quota-Limit, X-Quota-Used, X-Quota-Remaining, and X-Quota-Reset.

Full example

curl -X POST https://api.squillify.com/v1/execute \
  -H "X-API-Key: sq_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "skillKey": "text.slugify",
    "input": { "text": "Quarterly Report: Europe / Q1 2026" }
  }'

Catalog endpoints (public)

The catalog is open to everyone — no authentication needed. To keep it healthy for all, it’s rate-limited to 60 requests per minute per IP.

GET /api/v1/catalog/skills

Browse the MicroSkills in the public catalog. You’ll get a paginated response so large catalogs stay easy to page through.

{
  "data": [
    {
      "name": "text.slugify",
      "version": "1.0.0",
      "category": "text",
      "categoryLabel": "Text Processing",
      "title": "Slugify text",
      "summary": "Converts text into a lowercase URL-safe slug.",
      "description": "Converts arbitrary text into a lowercase, hyphen-separated, URL-safe slug...",
      "deterministic": true,
      "mode": "strict",
      "latencyClass": "instant",
      "tags": ["text", "url", "slug"],
      "capabilities": ["DETERMINISTIC"],
      "inputSchema": [
        {
          "name": "text",
          "type": "string",
          "description": "The text to slugify.",
          "required": true
        }
      ],
      "outputSchema": [
        {
          "name": "slug",
          "type": "string",
          "description": "The generated slug.",
          "required": true
        }
      ],
      "costModel": {
        "meter": "calls",
        "creditWeight": 1,
        "description": "1 execution credit per call"
      },
      "relevance": 0.95,
      "deprecated": false
    }
  ],
  "limit": 20,
  "cursor": "20",
  "hasMore": true,
  "totalCount": 44,
  "schemaVersion": "1.0"
}

When you search (q), each result comes with a relevancescore so you can see how well it matched. Once you’ve reached the last page, the cursor field comes back as null.

GET /api/v1/catalog/skills/{name}

Get the full picture of a specific MicroSkill, including its complete input and output schemas and the embedded documentation that comes with it — examples, use cases, and related MicroSkills.

GET /api/v1/catalog/skills/{name}/{version}

Pin down and fetch a specific version of a MicroSkill.

GET /api/v1/catalog/skills/{name}/docs

Pull the documentation for a specific MicroSkill — everything you need to get going, including examples, recommended use cases, related MicroSkills, and agent guidance.

GET /api/v1/catalog/categories

List every MicroSkill category, each with its tool count.

[
  { "value": "text", "label": "Text Processing", "toolCount": 25 },
  { "value": "schema", "label": "Schema Validation", "toolCount": 7 },
  { "value": "platform", "label": "Platform Utilities", "toolCount": 5 },
  { "value": "data", "label": "Data Processing", "toolCount": 1 },
  { "value": "security", "label": "Security", "toolCount": 1 },
  { "value": "math", "label": "Mathematics", "toolCount": 1 }
]

GET /api/v1/catalog/sitemap

Grab sitemap data for all public MicroSkills — handy when you’re generating a static site.

Runtime skill discovery (API key)

Want to discover skills straight over REST, scoped to exactly what your API key can use? These three endpoints let you browse, search, and fetch contracts without loading the whole catalog into context. They’re authenticated with your API key, and they never run a skill, touch your quota, or count against billing.

GET /v1/runtime/skills

Browse the skills your key can use, in a stable order. This is a plain listing — it doesn’t rank, so it turns away search-only params like query and includeContract.

GET /v1/runtime/skills/search

Ranked search across the skills your key can use. A non-blank queryis required — if you just want to list, use browse above. When exactly one skill matches, you can have us embed its full contract right in the result.

{
  "items": [
    {
      "skillKey": "identity.validate_email_syntax",
      "name": "identity.validate_email_syntax",
      "description": "Validate whether a string follows a valid email address syntax.",
      "latestVersion": "1.0.0",
      "deprecated": false,
      "executable": true,
      "contractUrl": "/v1/runtime/skills/identity.validate_email_syntax/contract",
      "matchType": "FUZZY",
      "relevanceScore": 0.94,
      "rank": 1
    }
  ],
  "nextCursor": null,
  "totalAvailable": 44,
  "totalMatches": 3,
  "queryUsed": "email validation",
  "contractExpanded": false,
  "contractExpansionMode": "none"
}

Send a categoryand we’ll also return a categoryResolution object telling you how we interpreted it (requested, resolved, mode, confidence, and taxonomyVersion). totalAvailable and totalMatches are always scoped to what your key can reach.

GET /v1/runtime/skills/{skillKey}/contract

Fetch the versioned input/output contract, limits, deprecation state, executability, and a contractDigest for one skill. Pass an optional versionto pin it. If the skill doesn’t exist or isn’t available to your key, you get a single, non-revealing 404 SKILL_NOT_FOUND either way.

MCP transport

You authenticate the MCP endpoint with X-API-Key or Authorization: Bearer sq_live_*. When you’re ready to wire it up, the MCP Connection docs walk you through the configuration.

Error handling

When something goes wrong, you’ll always get the same consistent JSON shape back — no guessing how to parse it:

{
  "error": {
    "code": "SKILL_NOT_ACCESSIBLE",
    "message": "The requested skill is not accessible with the current credentials.",
    "request_id": "a1b2c3d4-..."
  }
}

You’ll find the request_id field on execution errors. Authentication errors from the API key filter omit it.

Common error codes

Health check

The health and info endpoints are always open and never ask for authentication, so you can check on us anytime:

curl https://api.squillify.com/actuator/health

{ "status": "UP" }

Authenticated endpoints

Once you’re authenticated, you get more than the public catalog and the execute endpoint. Here are the endpoint groups open to you:

API key endpoints (runtime)