API Documentation

Complete reference for the SOM Cache API — the semantic CDN for AI agents.

Authentication

All API requests (except /v1/health) require a Bearer token in the Authorization header:

Header

Authorization: Bearer sk_som_your_api_key_here

Don't have a key yet? Sign up at cache.plasmate.app to get your API key.

Base URL

https://cache.plasmate.app

All endpoints are relative to this base URL.

GET /v1/som

Look up the cached SOM (Semantic Object Model) for a single URL. If the URL hasn't been crawled yet or the cache is stale, a live crawl is triggered via Plasmate.

Parameters

urlREQUIRED string The URL to look up. Must be URL-encoded.

fresh boolean Force a re-crawl even if a cached version exists. Default: false

Example Request

curl

curl "https://cache.plasmate.app/v1/som?url=https%3A%2F%2Fstripe.com%2Fpricing" \
  -H "Authorization: Bearer sk_som_your_key"
      

Example Response

200 OKjson

{
  "url": "https://stripe.com/pricing",
  "cached": true,
  "cache_tier": "hot",
  "som": {
    "elements": 142,
    "tree": [
      {
        "tag": "h1",
        "text": "Pricing",
        "role": "heading",
        "children": []
      }
    ]
  },
  "stats": {
    "raw_html_bytes": 284000,
    "som_bytes": 8200,
    "compression_ratio": 34.6,
    "tokens_saved": 68000
  },
  "crawled_at": "2025-03-23T18:42:00Z",
  "ttl_seconds": 3600
}
      

Error Codes

Code	Description
`400`	Missing or invalid `url` parameter
`401`	Missing or invalid API key
`429`	Rate limit exceeded
`502`	Upstream crawl failed

POST /v1/som/batch

Look up multiple URLs in a single request. Returns an array of results in the same order as the input. Maximum 50 URLs per request.

Request Body

urlsREQUIRED string[] Array of URLs to look up. Max 50.

Example Request

curl

curl -X POST "https://cache.plasmate.app/v1/som/batch" \
  -H "Authorization: Bearer sk_som_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://stripe.com/pricing",
      "https://openai.com/api/pricing",
      "https://anthropic.com"
    ]
  }'
      

Example Response

200 OKjson

{
  "results": [
    {
      "url": "https://stripe.com/pricing",
      "cached": true,
      "cache_tier": "hot",
      "som": { /* ... */ },
      "stats": { /* ... */ }
    },
    // ... one entry per URL
  ],
  "total": 3,
  "cached_count": 2,
  "crawled_count": 1
}
      

Error Codes

Code	Description
`400`	Missing `urls` array or exceeds 50 URL limit
`401`	Missing or invalid API key
`429`	Rate limit exceeded

GET /v1/som/diff

Detect changes in a page's semantic structure since a given date. Returns the diff between the stored version at the since timestamp and the current version.

Parameters

urlREQUIRED string The URL to check for changes.

sinceREQUIRED string ISO 8601 date. Compare against this timestamp.

Example Request

curl

curl "https://cache.plasmate.app/v1/som/diff?url=https%3A%2F%2Fstripe.com%2Fpricing&since=2025-03-20T00:00:00Z" \
  -H "Authorization: Bearer sk_som_your_key"
      

Example Response

200 OKjson

{
  "url": "https://stripe.com/pricing",
  "changed": true,
  "since": "2025-03-20T00:00:00Z",
  "current_crawled_at": "2025-03-23T18:42:00Z",
  "diff": {
    "added": 3,
    "removed": 1,
    "modified": 5,
    "elements": [
      {
        "action": "modified",
        "selector": "h2.pricing-title",
        "old_text": "$25/mo",
        "new_text": "$30/mo"
      }
    ]
  }
}
      

Error Codes

Code	Description
`400`	Missing `url` or `since` parameter
`401`	Missing or invalid API key
`404`	No cached data exists for this URL before `since`
`429`	Rate limit exceeded

GET /v1/health

Health check and cache statistics. No authentication required.

Example Request

curl

curl "https://cache.plasmate.app/v1/health"

Example Response

200 OKjson

{
  "status": "ok",
  "cached_urls": 85,
  "uptime_seconds": 432000
}
      

Rate Limits

Rate limits are enforced per API key. Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

Tier	Requests / Minute
Free	100
Developer	500
Business	2,000
Enterprise	Custom

Batch requests count as one request regardless of the number of URLs.

Errors

All errors follow a consistent JSON format:

Error Responsejson

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after 12 seconds.",
    "status": 429
  }
}
      

Error Codes

HTTP	Code	Description
400	`invalid_request`	Malformed request or missing required params
401	`unauthorized`	Missing or invalid API key
403	`forbidden`	API key doesn't have access to this endpoint
404	`not_found`	Resource not found (e.g., no diff history)
429	`rate_limit_exceeded`	Too many requests
502	`crawl_failed`	Upstream crawl via Plasmate failed
503	`service_unavailable`	Cache temporarily unavailable

SDKs COMING SOON

Official client libraries are in development:

Python

# pip install som-cache
from som_cache import SOMClient

client = SOMClient(api_key="sk_som_...")
result = client.lookup("https://stripe.com/pricing")
print(result.stats.compression_ratio)  # 34.6
      

Node.js

// npm install @plasmate/cache
import { SOMCache } from '@plasmate/cache';

const cache = new SOMCache({ apiKey: 'sk_som_...' });
const result = await cache.lookup('https://stripe.com/pricing');
console.log(result.stats.compression_ratio); // 34.6
      

Want early access to an SDK? Sign up and we'll notify you when they ship.