# info.summary
Search the public, evidence-backed Ginse index.

# info.description
An evidence-backed, human-moderated index for finding agent-native tools whose core job is directly operable through an API, CLI, or MCP. The read-only catalog API requires no authentication. Optional, rate-limited mutations can create an unlisted 30-day scan card or queue one exactly previewed external candidate for human review after separate explicit consent. Stable operations are namespaced under /api/v1. Unversioned compatibility routes remain available during the v1 transition but are not the durable integration contract.

# x-api-lifecycle.compatibilityRoutes
Unversioned /api routes are transitional aliases. A future sunset will be announced in the developer guide and with Deprecation and Sunset response headers before removal.

# x-async-jobs.reason
Every published v1 operation is a bounded catalog read or small transactional mutation and completes synchronously; Ginse does not expose long-running API work.

# tags[].description
Discover and compare admitted agent-native tools.

# tags[].description
Read anonymized AX reviews or manage a signed-in reviewer's own review.

# tags[].description
Create, read, or revoke privacy-minimal 30-day scan cards.

# tags[].description
Queue a consented external candidate for human admission review.

# paths./api/v1/catalog.get.description
Returns only tools admitted under the Ginse agent-native standard: an agent can complete the core job end to end through an API, CLI, or MCP. Results are paginated with an integer cursor.

# paths./api/v1/catalog.get.parameters[].description
Case-insensitive search across name, domain, tagline, category, admitted interfaces, core job, and analysis evidence.

# paths./api/v1/catalog.get.parameters[].description
Zero-based result offset from a previous nextCursor.

# paths./api/v1/catalog.get.responses.200.headers.Cache-Control.description
Catalog reads use a short shared cache with stale-while-revalidate.

# paths./api/v1/replacements.get.description
Ranks eligible Ginse listings against an incumbent name and a primary job supplied by the user or inferred locally by their agent. Every successful response includes one personal next action; a no-match response recommends a concrete keep-and-measure step rather than inventing a candidate.

# paths./api/v1/replacements.get.parameters[].description
The primary job to match, supplied by the user or inferred locally by their agent.

# paths./api/v1/replacements.get.responses.200.description
Credible alternatives or an explicit no-credible-replacement outcome, always with one personal next action.

# paths./api/v1/scan-shares.post.description
Use only after the person has seen the private report, reviewed the exact public preview, and explicitly chosen to create a link. The server accepts a percentage plus one to three public Ginse catalog recommendation IDs and action kinds. Each recommendation may optionally include one or two exact public catalog IDs it replaces. The server never accepts raw inventory, usage, jobs, history, hours, AX components, identity, free-form incumbent names, or report text.

# paths./api/v1/scan-shares.post.parameters[].description
Optional for verified signed-in callers. Use a unique high-entropy 32–128 character URL-safe key. The key is scoped to the verified account; same-body concurrent retries create one card and consume quota once. Reusing it with a different body returns 409.

# paths./api/v1/scan-shares.post.responses.201.description
An unlisted card URL and private revocation token.

# paths./api/v1/scan-shares/{slug}.get.responses.200.description
The privacy-minimal public card projection.

# paths./api/v1/submissions.post.summary
Queue one discovered candidate for review

# paths./api/v1/submissions.post.description
Use only after showing the person the exact name, canonical product URL, API/CLI/MCP interface, core-job claim, and first-party evidence URL and receiving separate explicit consent. This mutation is distinct from scan sharing: it accepts no inventory, usage, history, incumbent names, identity, credentials, report text, or fetched page content. A candidate remains pending and unranked until human admission review; submission never makes it eligible or public.

# paths./api/v1/submissions.post.parameters[].description
Fresh high-entropy 32–128 character URL-safe key. Same-key same-body retries replay the result without consuming quota; reuse with a different body returns 409.

# paths./api/v1/submissions.post.responses.202.description
The candidate is pending review, or an existing candidate was found.

# paths./api/v1/reviews.get.responses.200.description
Approved public reviews, current AX summary, and the signed-in caller's own review when present.

# paths./api/v1/reviews.put.summary
Create or replace the signed-in reviewer's review

# paths./api/v1/reviews.put.description
Requires a verified-email session. Editing an approved review returns it to pending moderation; hidden reviews cannot be resubmitted by their author.

# paths./api/v1/reviews.put.responses.200.description
The review was saved and is pending moderation.

# paths./api/v1/reviews.delete.summary
Soft-delete the signed-in reviewer's review

# paths./api/v1/health.get.description
Verifies that the public API can reach the eligible catalog dependency.

# components.responses.MutationError.description
The review request could not be completed.

# components.responses.ShareMutationError.description
The scan-share request could not be completed.

# components.responses.SubmissionMutationError.description
The discovery submission could not be completed.

# components.responses.RateLimited.description
The applicable request quota is exhausted.

# components.headers.ApiVersion.description
Stable major API version used for this response.

# components.headers.RateLimitPolicy.description
Quota policy metadata using HTTPAPI RateLimit structured-field syntax.

# components.headers.RateLimit.description
Measured remaining requests and seconds until the current fixed window resets.

# components.headers.RetryAfter.description
Seconds to wait before retrying a throttled request.

# components.headers.IdempotencyReplayed.description
Present and true only when an Idempotency-Key replay returns the original result.

# components.securitySchemes.cookieAuth.description
Short-lived access-token cookie established by GitHub or Google OAuth.

# components.schemas.Tool.properties.agentScore.description
Legacy mixed-method score retained temporarily for v2 clients. Null means no legacy score has been assigned; it is not the three-source AX score.

# components.schemas.AxSummary.properties.score.description
Exact equal-third mean when all three current components exist; otherwise null.

# components.schemas.ReplacementAlternative.properties.scoreableOrigin.description
Root product origin safe to send to an external AX provider, or null when the product identity depends on a path or shared platform.

# components.schemas.PersonalNextAction.properties.summary.description
The single recommended move for this incumbent and inferred job.

# components.schemas.PersonalNextAction.properties.firstTrial.description
A bounded, reviewable action that remains useful when score or usage evidence is missing.

# components.schemas.ScanShareRecommendationInput.properties.replaces.description
Optional, separately previewed public catalog IDs replaced by this recommendation. Omit instead of sending private names or inventory.

# components.schemas.ScanShareCreateResponse.properties.revokeToken.description
Returned only on successful creation, including verified account-scoped idempotent replay. Keep private and never append to the share URL.

# components.schemas.DiscoverySubmissionInput.properties.evidenceUrl.description
Public first-party HTTPS evidence for the claimed interface and core job.

# components.schemas.DiscoverySubmissionResponse.properties.duplicate.description
True when the canonical candidate already existed; an existing pending candidate is a successful outcome.

# components.schemas.ScanShareRecommendation.properties.toolId.description
Public catalog ID. Stable detail URL: /tools/<URL-encoded toolId>.

# components.schemas.ScanShareReplacement.properties.toolId.description
Public catalog ID. Stable detail URL: /tools/<URL-encoded toolId>.