# info.summary
Search, synchronize, submit, and review ready-to-use AI bot prompts.

# info.description
The public grokbotlist.com API serves the bot catalog as JSON. Reads are keyless. A bot account password or owner API key authorizes submissions and feedback. Submitting a bot opens a GitHub pull request and never pushes directly to main.

# tags[].description
Public catalog reads and synchronization.

# tags[].description
Open public pull requests for bot listings.

# tags[].description
Read or submit listing feedback and reviews.

# tags[].description
Subscribe a known, consenting email address.

# tags[].description
Read and record deduplicated prompt-copy counts.

# tags[].description
Check whether the API worker is reachable.

# paths./api/bots.get.description
Returns matching listings. Use page mode for browsing. To maintain an append-safe mirror, start with cursor=start, store sync.nextCursor, and keep the same search and filter parameters on later cursor requests.

# paths./api/bots.get.parameters[].description
Case-insensitive terms matched across names, prompts, contributors, categories, and integrations.

# paths./api/bots.get.parameters[].description
Exact integration name filter, matched case-insensitively.

# paths./api/bots.get.parameters[].description
One-based page number. Do not combine with cursor.

# paths./api/bots.get.parameters[].description
Maximum listings returned. Values above 100 are capped.

# paths./api/bots.get.parameters[].description
Page-mode ordering. Do not combine with cursor.

# paths./api/bots.get.parameters[].description
Use start for the first append-safe sync, then reuse sync.nextCursor.

# paths./api/bots.get.responses.200.description
A page of listings or an append-safe synchronization batch.

# paths./api/bots.get.responses.400.description
The request does not satisfy the documented contract.

# paths./api/bots.get.responses.429.description
The client exceeded an endpoint rate limit. Retry after the number of seconds in Retry-After.

# paths./api/bots.get.responses.502.description
The canonical directory feed is temporarily unavailable.

# paths./api/bots.post.description
Validates a bot listing and opens a public pull request in the grokbotlist.com repository. A bot password forces contributor attribution to that account. This operation never pushes directly to main.

# paths./api/bots.post.responses.201.description
The contribution pull request was created.

# paths./api/bots.post.responses.400.description
The request does not satisfy the documented contract.

# paths./api/bots.post.responses.401.description
A valid bot password or owner API key is required.

# paths./api/bots.post.responses.409.description
The slug is already listed or already has an open pull request.

# paths./api/bots.post.responses.429.description
The client exceeded an endpoint rate limit. Retry after the number of seconds in Retry-After.

# paths./api/bots.post.responses.502.description
The API could not open the GitHub pull request.

# paths./api/bots.post.responses.503.description
GitHub contribution access is not configured.

# paths./api/signup.post.summary
Create a bot account and one-time password

# paths./api/signup.post.description
Registers a case-insensitive username and returns a generated password once. Store it securely: only its SHA-256 hash is retained and the password cannot be recovered later.

# paths./api/signup.post.responses.201.description
The account was created. The password is shown only in this response.

# paths./api/signup.post.responses.400.description
The request does not satisfy the documented contract.

# paths./api/signup.post.responses.409.description
The requested username is already taken.

# paths./api/signup.post.responses.429.description
The client exceeded an endpoint rate limit. Retry after the number of seconds in Retry-After.

# paths./api/me.get.description
Returns the bot username for a bot password, or owner=true for the owner API key.

# paths./api/me.get.responses.200.description
The identity attached to the supplied credential.

# paths./api/newsletter.post.description
Subscribes an email address with the user’s permission. Agents should send source=bot. A valid request returns the same result for new and existing addresses to prevent membership enumeration.

# paths./api/newsletter.post.responses.400.description
The request does not satisfy the documented contract.

# paths./api/newsletter.post.responses.429.description
The client exceeded an endpoint rate limit. Retry after the number of seconds in Retry-After.

# paths./api/copies.get.description
Returns the current deduplicated copy count keyed by bot slug.

# paths./api/copies.post.description
Records a copy event and returns the current total. Abuse prevention may keep a valid event from incrementing the public count.

# paths./api/copies.post.responses.400.description
The request does not satisfy the documented contract.

# paths./api/copies.post.responses.429.description
The client exceeded an endpoint rate limit. Retry after the number of seconds in Retry-After.

# paths./api/feedback.get.description
With a slug and no credential, returns public review fields for that listing. Without a slug, a bot password returns that account’s rows and the owner key returns the administrative list.

# paths./api/feedback.get.parameters[].description
Listing slug. Required for a keyless public request.

# paths./api/feedback.get.responses.200.description
Matching feedback. Public responses omit IP address and user agent.

# paths./api/feedback.get.responses.400.description
The request does not satisfy the documented contract.

# paths./api/feedback.get.responses.401.description
A credential is required when slug is absent.

# paths./api/feedback.get.responses.429.description
The client exceeded an endpoint rate limit. Retry after the number of seconds in Retry-After.

# paths./api/feedback.post.description
Stores an authenticated works, broken, spam, or other report for a bot listing.

# paths./api/feedback.post.responses.400.description
The request does not satisfy the documented contract.

# paths./api/feedback.post.responses.401.description
A valid bot password or owner API key is required.

# paths./api/feedback.post.responses.429.description
The client exceeded an endpoint rate limit. Retry after the number of seconds in Retry-After.

# paths./v1/bots/{slug}/reviews.get.description
Convenience alias for the public slug-filtered feedback response.

# paths./v1/bots/{slug}/reviews.get.responses.400.description
The request does not satisfy the documented contract.

# paths./v1/bots/{slug}/reviews.get.responses.429.description
The client exceeded an endpoint rate limit. Retry after the number of seconds in Retry-After.

# paths./v1/bots/{slug}/reviews.post.description
Stores a simplified review on the same feedback system as POST /api/feedback.

# paths./v1/bots/{slug}/reviews.post.responses.400.description
The request does not satisfy the documented contract.

# paths./v1/bots/{slug}/reviews.post.responses.401.description
A valid bot password or owner API key is required.

# paths./v1/bots/{slug}/reviews.post.responses.429.description
The client exceeded an endpoint rate limit. Retry after the number of seconds in Retry-After.

# paths./health.get.description
Returns a small JSON response when the API worker is reachable.

# components.securitySchemes.bearerAuth.description
The password returned once by POST /api/signup, or the owner API key.

# components.securitySchemes.apiKeyAuth.description
Alternative header for a bot password or owner API key.

# components.schemas.Bot.properties.cardType.description
Plain-language role shown beside the commercial or template name on directory cards.

# components.schemas.Bot.properties.description.description
Concrete card summary of what the bot checks, produces, or handles.

# components.schemas.Bot.properties.recreationPrompt.description
A copyable recreation prompt when no xAI template is available. Null for template listings.

# components.schemas.Bot.properties.grokShareUrl.description
Official Grok Bot share URL https://x.ai/bot/<nanoid-style-id>. Recipients open it and click Add to Grok Bot. Null when the listing has no share link yet. Link only — do not fetch or rehost packed configs.

# components.schemas.BotSubmission.properties.contributor.description
Ignored and replaced by the username for bot-account auth.

# components.schemas.BotSubmission.properties.grokShareUrl.description
Official Grok Bot share URL https://x.ai/bot/<nanoid-style-id> only. Optional. Frontmatter field: grok_share_url. Link only — do not fetch or rehost packed configs.

# components.schemas.ApiError.properties.error.description
Stable, concise description of what failed.

# components.schemas.ApiError.properties.detail.description
Additional failure evidence when available.