Capability Slugs for API Discovery

Capability slugs for API discovery are machine identifiers, not miniature marketing headlines. A label can improve as buyers change their vocabulary, but the slug behind a catalogue job has to keep resolving because URLs, cached records, provider mappings and stored decisions may already depend on it.

That difference is easy to miss when the slug is readable. `company-domain-lookup` looks like copy, so changing it to `business-domain-search` feels like an editorial cleanup. To a client that stored the first value, it is an identifier replacement. The words may describe nearly the same job while the system now sees two unrelated keys.

Give the job one identity and several descriptions

A capability record needs one canonical identifier for machines and separate fields for language intended for people or retrieval. The slug should identify the bounded job. The display label should explain it. The description should name the input and result. Aliases should capture the other phrases buyers use for the same work.

That separation lets you improve discovery without changing identity. A provider can add “company website matching” as an alias for a job whose canonical slug remains `company-domain-lookup`. Search can learn the new phrase, while `/v1/capabilities/company-domain-lookup`, existing catalogue entries and analytics continue to point at the same record.

This builds on an API capability taxonomy for agents, but it solves a narrower problem. Taxonomy work decides whether two offers perform the same job. Slug governance makes sure the identifier for that agreed job survives edits to its label and description.

The same pattern appears in established API design. A resource has a canonical name that callers store, while a separate display name can change. OpenAPI gives an operation a unique `operationId` distinct from its summary and description. The exact fields differ, but the boundary is the same: mutable explanation should not double as persistent identity.

Know what the slug anchors downstream

Before changing a capability slug, list every place where it is treated as data. The obvious dependency is the catalogue route. The less visible dependencies are the ones that turn a rename into a quiet discovery failure.

Check at least these surfaces:

• catalogue paths such as `/v1/capabilities/{slug}` and any generated links;
• provider records that assign an endpoint to the capability;
• crawler exports, x402 discovery records and cached catalogue snapshots;
• exact-match rules, synonym maps and search indexes;
• dashboards, logs and alerts grouped by the slug;
• saved queries, evaluation fixtures and integration tests;
• decision records that preserve which job produced the candidate set;
• MCP tool descriptions or workflow configuration that embeds the identifier.

A broken dependency does not always return an error. A cached crawler may simply keep the old record. A provider mapping may produce an empty capability page. An evaluation may start measuring the new slug as a fresh job with no history. Those outcomes look like lower demand or missing providers, even though the cause is an identifier migration.

The metadata agents actually read should therefore carry both identity and freshness. A canonical slug tells the consumer what record it has. An update marker tells it whether that record should replace a cached copy.

Keep versions out of a stable job identifier

Do not put a release date, schema version or provider version into the capability slug unless the job itself is materially different. `invoice-line-item-extraction-v2` creates a new discovery identity when the likely change is a new request schema or implementation. Every provider and consumer then has to migrate even if the buyer still asks for the same result.

Version the contract at the layer that changed. A provider route can publish a new request schema. A listing can carry an updated timestamp. An OpenAPI document can describe a new operation version. The capability remains the stable join key when the input can still be mapped and the result still satisfies the same bounded job.

A new capability is justified when substitution stops being honest. If the old job returns extracted invoice line items and the new one returns a tax-compliance judgment, those are different results with different buyer intent. Give them separate slugs and classify providers deliberately. Do not hide a semantic split behind a version suffix or reuse the old slug for a different job.

Treat a rename as a compatibility migration

Sometimes the old slug is genuinely wrong. It may contain a vendor term, describe work the candidates do not share or collide with a better-defined job. In that case, run a migration instead of a replacement.

Create the new canonical record first. Map the old slug to it as an alias. Keep the old catalogue path resolving, and return the canonical slug in the response so clients can update stored references. If the slug is part of an HTTP URI, a permanent redirect can help browser-like clients, but it is not the whole migration. JSON consumers, cached exports and exact-match rules may never follow that route.

Update provider mappings, discovery documents, search indexes and tests in the same release. Then measure requests that still arrive through the alias. Retire it only when the callers and controlled caches that matter have moved. This is the operational counterpart to keeping a crawler-readable API catalogue: the old address must remain understandable long enough for distributed readers to converge.

Test identity separately from search relevance

Discovery tests should prove two different properties. Identity tests prove that the same slug resolves to the same bounded job over time. Retrieval tests prove that changing buyer language still reaches that job.

For identity, fetch the canonical capability route, follow any supported alias and confirm both responses identify the same canonical slug. Check that reviewed providers remain assigned and that stored fixtures or decision references still resolve. For retrieval, query `GET /v1/discover?q=…` with the old label, the new label and common task phrases. They should reach the same capability without creating duplicate candidate sets.

Do not use an external hit as proof that the migration worked. Apiosk returns external x402 results separately in `external_candidates`. Those records have no `candidate_id`, are unreviewed and unmeasured, and cannot chain into comparison or decision. A successful external text match proves reach, not catalogue continuity.

Where Apiosk fits

Apiosk exposes catalogue jobs through `GET /v1/capabilities` and `/v1/capabilities/{slug}`, with candidates for one job ordered cheapest first. `GET /v1/discover?q=…` handles the buyer’s task language and returns reviewed candidates with stable `candidate_id` values. Those candidate IDs, not a display label, continue into comparison and decision.

For providers, the practical rule is simple: list the bounded job your API performs, keep its capability slug stable and update descriptive language through labels and aliases. If a rename is unavoidable, preserve the old identifier as a resolvable alias until dependent records have moved.

Apiosk then carries reviewed candidates into `/v1/compare` and `/v1/decide`. Comparison covers price, settlement rail, input compatibility and sufficiently measured latency and success rate. Scores are relative to that candidate set, include their weights and contributions, and drop and name unmeasured dimensions. Result quality and provider terms are not measured. Stable capability identity does not improve those facts; it keeps the correct job and providers connected while the catalogue evolves.