Which Sume API routes are missing from the public OpenAPI document?

Five route families are implemented on the API but left out of the public OpenAPI document: the asset routes under /v1/assets, POST /v1/generation/admission-preview, the create calls POST /v1/avatars and POST /v1/avatar-videos, the unversioned /health, and the generic template path for model runs. The API reference calls this hiding on purpose, and it asks you not to treat these routes as a documented public contract.

This is a contract question, not a bug. The API implements those routes, but the team keeps them out of the public document on purpose, and the docs tell you not to use them as a documented public contract until they come back. The practical effect is that a client generated from the document will simply not have methods for them.

Why a generated client has gaps

A generated client only knows what the document lists. If you ask your code generator for an upload method or an admission preview, it will not exist, and the absence is not a sign that the route is gone. It is a sign that the route is not part of the stable surface yet.

If you generate a client from the OpenAPI document, expect gaps exactly where the table says. Do not patch the document by hand. A hand edited schema drifts from the server, and the next regeneration removes your changes. Write a small function next to the generated client for each hidden route that you really need, and mark it clearly in your code as outside the public contract.

What to use instead

Use this table to decide what to call instead.

The asset helpers are the case that most teams meet first. The docs say that in generation requests it is better to use public HTTPS media URLs, so the upload path is rarely needed. When you do need it, uploadFile in the SDK does the three steps for you: it asks for an upload URL, puts the bytes to storage and then completes the asset.

Check the live document

Check for a route before you depend on it. The script below downloads the public document and tests for a path. It uses only the standard library, and it needs no key, because the OpenAPI document is one of the public routes.

A short list helps when you review a vendor integration. Count how many of your calls touch a hidden route, and write the number down. If it is zero, you rely only on the public contract. If it is not zero, those calls are the first places to look when a release changes behaviour.

import json, urllib.request

def paths(url="https://api.sume.com/v1/openapi.json"):
    req = urllib.request.Request(url, headers={"User-Agent": "docs-sample/1.0"})
    with urllib.request.urlopen(req, timeout=30) as r:
        return set(json.load(r).get("paths", {}))

def missing(wanted, available):
    return sorted(p for p in wanted if p not in available)

if __name__ == "__main__":
    have = paths()
    print(len(have) > 0)
    print(missing(["/v1/jobs/{id}/status", "/v1/assets/upload-url"], have))

Reading the result

Read the output with care. Path parameter names in the document may differ from the form you wrote, so print a few paths first and match them by pattern. A route that is absent from the document can still work when you call it, and a route in the document can still return a 4xx because of a scope or a plan, so the document tells you what is promised and not what your key may do.

Make the check part of CI. Download the document, look for the path you depend on, and fail the build with a clear message when it is missing. That turns a surprise on a Friday into a red check on a pull request.