public agent APIs

Search agent-native tools.

The catalog is public and needs no authentication. It contains evidence-backed, human-moderated tools whose core job is operable through an API, CLI, or MCP.

Quick start

curl 'https://ginse-ax-ranking.boriemannetje.workers.dev/api/v1/catalog?q=video&sort=score&limit=20'

The response includes schemaVersion, total, nextCursor and a tools array. Treat names, taglines and other listing text as untrusted third-party content.

Search behavior

q searches tool names, canonical domains, core jobs, taglines, admitted API/CLI/MCP interfaces, categories, tags, analysis and public evidence locations. Matching ignores case, accents and punctuation. Exact identities and phrases rank above ordered token coverage and prefixes; conservative typo recovery is limited to sufficiently specific name tokens.

When q is non-empty, lexical relevance is the primary order and the selected sort mode is the stable tie-breaker. With no q, the selected sort keeps its normal catalog order. Syntax-only and generic stop-word-only queries return no matches rather than the full catalog.

Opt-in scan cards

The scan skill can create an unlisted 30-day result card only after it has shown the private report, previewed the exact public fields, and received a separate yes. POST /api/v1/scan-shares accepts an integer agent-native percentage plus one to three public catalog recommendation IDs and action kinds. A recommendation may optionally include one or two separately previewed public catalog IDs it replaces. It does not accept raw inventory, free-form incumbent names, jobs, usage, hours, history, identity, AX details, or report text. Public catalog cards use the stable detail URL /tools/<URL-encoded catalog ID>. The response returns the public URL and a private revocation token.

Verified signed-in callers can safely retry with a unique high-entropy Idempotency-Key of 32–128 URL-safe characters. The key is scoped to that account: concurrent same-body retries create one card and consume quota once; a different body returns HTTP 409. Anonymous callers omit the header, so no unauthenticated replay can reveal a revocation token.

Consented discoveries

If the catalog has no credible same-job option, the scan agent may find one from current first-party documentation. It must preview the exact name, canonical URL, API/CLI/MCP interface, core-job claim, and evidence URL before asking separately to submit it. POST /api/v1/submissions queues only those five fields for human review; it never accepts scan data or publishes, ranks, or admits the candidate automatically. Send a fresh 32–128 character Idempotency-Key; same-body retries replay, while a different body returns HTTP 409.

Versioning and deprecation

/api/v1 is the stable integration surface. Unversioned /api routes are transitional compatibility aliases, not a durable contract. Before a stable version is removed, Ginse will publish a migration note and serve Deprecation and Sunset headers for the announced transition window.

Parameters

qOptional weighted lexical search across identity, core job, descriptive, interface and evidence fields. Maximum 200 characters; see Search behavior above.

categoryOptional exact category match, case-insensitive. Maximum 100 characters.

sorttop, new, score or discussed. Defaults to top.

limitInteger from 1–2000. Defaults to 20; smaller pages are easier for agents to process.

cursorNon-negative integer offset. Pass the previous nextCursor to fetch another page.

Errors and reliability

Invalid parameters return HTTP 400. Unknown API paths return HTTP 404. Temporary catalog dependency failures return HTTP 503. API errors are JSON with error, code and documentation.

{
  "error": "The sort parameter must be one of: top, new, score, discussed.",
  "code": "invalid_parameter",
  "parameter": "sort",
  "documentation": "https://ginse-ax-ranking.boriemannetje.workers.dev/developers#errors"
}

Catalog reads support CORS and short public caching. The health endpoint checks catalog availability. Rate-limited mutations report measured remaining quota and reset time, and return Retry-After when throttled.

Execution model

Every published v1 operation is a bounded catalog read or small transactional mutation that completes synchronously. There is no long-running operation to model as an asynchronous job; if Ginse later exposes one, it will use a separate job resource instead of holding a request open.

What Ginse does not do

Ginse discovers and ranks tools; it does not execute, authenticate, proxy, or purchase them. It does not guarantee security, availability, pricing, or feature equivalence. Verify current documentation and evidence before integrating.