# submitby.ai
Projects can only be submitted through MCP or the API. No signup required.
Connect the MCP server in your agent before sending it the submission prompt.
Use the same origin that served this file, including on staging.
MCP: /mcp
OpenAPI: /api/v1/openapi.json
Guide: /for-agents

1. Ask the owner whether to add a visible badge for a free listing or skip it for $4.99 USD.
2. Call list_categories and list_tags (or get_taxonomy). Choose one primary category and suggest relevant tags.
3. Call submit_project with HTTPS URL, factual name and description, category, comma-separated tags, route (badge or paid), and a fresh 32+ character random idempotency_key.
4. Save control_token securely. Reuse the idempotency key only with identical input.
5. Add the returned project-specific badge or verification file to the project website.
6. Call verify_submission. Poll get_submission with the ID and control token. Follow next_actions.
7. Continue with payment only if the owner chose paid and site and content approval are complete. Use purchase_badge_waiver with method "mpp" only when you have an authorized MPP payment client. Otherwise use method "checkout".
8. Show /terms and /privacy before payment. For Checkout, show checkout_url to the owner. For MPP, follow the returned payment challenge with the payer's authorized payment client. Managed Checkout is sold through Link; direct MPP is sold by submitby.ai and does not use Managed Payments. Never ask for card details in chat.
9. Poll get_submission after payment. Payment is confirmed by Stripe, never by a browser return URL. Give the public listing URL only after publication.

MCP category/tag tools: list_categories, list_tags, get_taxonomy.
Public API lists: GET /api/v1/categories and GET /api/v1/tags.
Submitted category and tags accept vocabulary IDs, names, or aliases. Tags use a comma-separated string (maximum 20 suggestions). They guide classification but do not bypass checks.
Jev receives the suggestions plus parsed website metadata and text. It returns likelihoods for all tags. Private status exposes tag_likelihoods when classification is available.

Manual payment: POST /api/v1/submissions/:id/checkout without a submission token returns a Stripe Checkout URL. Anyone can pay for an eligible submission.
MPP: POST /api/v1/submissions/:id/payment without a submission token. When MPP is enabled, HTTP 402 and WWW-Authenticate describe the payment challenge. Authorization carries only the payer's payment credential. When MPP is disabled, the endpoint can return a Managed Checkout link instead.
Both methods share one purchase. Never pay again while an earlier payment or Checkout is pending.
If payments are disabled, ask whether the owner prefers the free badge route or waiting. Never switch routes without asking.
Payment waives only the badge. Website control and content approval remain required.

ChatGPT app: connect /mcp/chatgpt with authentication None. Tools: list_projects, get_taxonomy, submit_project, get_submission_status, get_badge, verify_submission. No signup or account linking.
ChatGPT submissions use the free badge route and expose public project details and status by submission ID. Use only public project information. The app does not expose editing credentials, updates, recovery tokens, payment tools, or checkout links.
Public badge code: GET /api/v1/submissions/:id/badge or get_badge(id), without authentication. Keep the unique submission link and data-submitby value: they bind website verification to one submission. Reading badge code does not grant editing rights.
Public ChatGPT status: GET /api/v1/submissions/:id/public. Private API drafts return 404 here. Existing authenticated private status and updates remain unchanged.