Which Sume API routes work without an API key?

Six routes work without a key: GET /v1/health, GET /v1/catalog, GET /v1/openapi.json, GET /v1/bgm/catalog, GET /v1/bgm/categories and POST /v1/bgm/pick. Every other /v1 route needs a Sume API key, sent as Authorization: Bearer or as x-api-key, and never both in one request.

The list is short on purpose. These are the routes that describe the service and do not touch your workspace, so they hold nothing private and cost nothing. Everything that creates, reads or changes work belongs to a workspace, and that is why it needs a key.

Keep the list in one place in your code, as a constant. A single list of public paths makes it clear to a reviewer which of your calls carry a credential and which do not, and it stops a key from being sent to routes that never needed it.

What each public route is good for

Use the public routes to check the service before you wire in a key. The health route confirms that the API is up. The catalog lists capabilities, endpoints, runtime readiness, models and pricing metadata. The OpenAPI document is what you feed to a client generator, and the background music routes let you browse and pick tracks.

A health check from a monitoring tool is the typical use. It needs no secret, so you can keep it out of the secret store of the monitor, and the response includes the build commit, which is handy when you wonder whether a fix has been deployed yet.

Try the routes

The sample calls the three simplest routes and prints what comes back. It uses only the standard library, it needs no key, and it fails loudly if a route stops answering.

Public does not mean unlimited. Anonymous reads share the per client IP budget, so a build server farm that sits behind one address shares one bucket. If many jobs in your CI call the catalog at the same moment, cache the response for the run instead of fetching it in each job.

import json, urllib.request

BASE = "https://api.sume.com/v1"

def get(path):
    req = urllib.request.Request(BASE + path, headers={"User-Agent": "docs-sample/1.0"})
    with urllib.request.urlopen(req, timeout=30) as r:
        return r.status, json.load(r)

status, health = get("/health")
print(status, health.get("status"))

status, spec = get("/openapi.json")
print(status, len(spec.get("paths", {})) > 0)

status, catalog = get("/catalog")
print(status, isinstance(catalog, dict))

Two details

Two routes in the list are worth a second look. The catalog is the right first call for a new integration, because the docs point to it when a model or resource is not found. And the unversioned /health is hidden, so use GET /v1/health in monitors and not the shorter path.

Remember the limit that applies. Unauthenticated requests are limited per client IP at the Free rate, with reads at four times the write rate, so a monitor that polls every second from one address will meet a 429 sooner than a keyed caller would. Poll at a sensible interval, such as once a minute.

The status code and the shape check in the sample are deliberately small. They tell you that the route answers and that the answer is JSON of the expected kind, which is what a smoke test needs, and they leave contract testing to a separate job with the OpenAPI document.

When a call needs a key

For everything else, a 401 means the key is missing, malformed or revoked, and the fix is to check the header. A 403 means the key is valid but lacks the scope or the workspace access, and the fix is a key with the right scope. Do not send the key in both headers at once, because the API answers 401 with the message that one credential is allowed.

When a route that should be public returns 401, check the path first. A typo such as /v1/catalogue is not on the list, and the API treats it as a normal route that needs a key.