{"openapi":"3.1.0","info":{"title":"Gecko public API","version":"1.0.0","summary":"Comprehend an API surface; join the waitlist.","description":"The public HTTP operations behind https://geckovision.tech. Gecko's full product surface for agents is the hosted MCP server (Streamable HTTP; see https://geckovision.tech/.well-known/mcp/server-card.json). These REST operations cover the landing's own interactive features. Docs: https://docs.geckovision.tech. VERSIONING: paths are versioned (/api/v1/...); the unversioned path is a permanent alias of the latest major version. A breaking change ships as /api/v2 with the v1 path kept for at least 90 days and answering with Deprecation and Sunset headers during that window. RETRIES: write-shaped operations accept an Idempotency-Key header; every operation here is idempotent by construction, so a retry with the same input never duplicates work. RATE LIMITS: responses carry the RFC RateLimit headers (RateLimit-Limit, -Remaining, -Reset) and a 429 carries Retry-After.","contact":{"name":"Gecko","email":"contact@geckovision.tech","url":"https://geckovision.tech"}},"servers":[{"url":"https://geckovision.tech","description":"The landing site"}],"paths":{"/api/v1/comprehend":{"post":{"operationId":"comprehendApiSurface","summary":"Comprehend an OpenAPI spec or docs URL into agent tools","description":"Point Gecko at a public OpenAPI spec URL (or a docs page with from_docs=true) and receive a preview of the agent tools it comprehends: tool names, counts, quarantine verdict, and the exact commands to add the surface to an MCP client. Control-plane only: the request is forwarded, nothing is stored. Private, internal, and non-HTTP URLs are refused.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Public https URL of an OpenAPI spec (or a docs page when from_docs is true)."},"from_docs":{"type":"boolean","default":false,"description":"Treat the URL as a human docs page and extract the API surface from it."}}}}}},"responses":{"200":{"description":"The comprehended surface preview.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComprehendResult"}}}},"400":{"description":"The URL was missing, malformed, non-public, or did not resolve to a comprehensible spec.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The spec is too large to comprehend right now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honor Retry-After and the RateLimit headers to self-throttle.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The comprehension service could not be reached.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/comprehend":{"post":{"operationId":"comprehendApiSurfaceUnversioned","summary":"Comprehend an OpenAPI spec or docs URL into agent tools","description":"Permanent alias of /api/v1/comprehend (the unversioned path always serves the latest major version). Point Gecko at a public OpenAPI spec URL (or a docs page with from_docs=true) and receive a preview of the agent tools it comprehends: tool names, counts, quarantine verdict, and the exact commands to add the surface to an MCP client. Control-plane only: the request is forwarded, nothing is stored. Private, internal, and non-HTTP URLs are refused.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Public https URL of an OpenAPI spec (or a docs page when from_docs is true)."},"from_docs":{"type":"boolean","default":false,"description":"Treat the URL as a human docs page and extract the API surface from it."}}}}}},"responses":{"200":{"description":"The comprehended surface preview.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComprehendResult"}}}},"400":{"description":"The URL was missing, malformed, non-public, or did not resolve to a comprehensible spec.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The spec is too large to comprehend right now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honor Retry-After and the RateLimit headers to self-throttle.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The comprehension service could not be reached.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/case-studies":{"get":{"operationId":"listCaseStudies","summary":"List Gecko case studies (cursor-paginated)","description":"The case studies this site publishes, as data: slug, title, summary, tags, intro, canonical page URL, and the external evidence link. Cursor-paginated: pass next_cursor from the previous page until it is null. Same single-source content the HTML pages render, so the API cannot drift from the site.","parameters":[{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from the previous page's next_cursor. Omit for the first page.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1-10.","schema":{"type":"integer","minimum":1,"maximum":10,"default":10}}],"responses":{"200":{"description":"One page of case studies.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["items","next_cursor"],"properties":{"items":{"type":"array","items":{"type":"object","required":["slug","title","summary","url"],"properties":{"slug":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"intro":{"type":["string","null"]},"url":{"type":"string","format":"uri"},"evidence_url":{"type":"string","format":"uri"}}}},"next_cursor":{"type":["string","null"],"description":"Pass as cursor to fetch the next page; null on the last page."}}}}}},"400":{"description":"Invalid cursor or limit.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honor Retry-After and the RateLimit headers.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/waitlist":{"servers":[{"url":"https://app.geckovision.tech","description":"The Gecko app (this operation is served there)"}],"post":{"operationId":"joinWaitlist","summary":"Join the Gecko waitlist","description":"Add an email to the provider waitlist. Duplicates are absorbed silently (the response never reveals whether an email was already present). One email is sent when a slot opens; nothing else.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","maxLength":254,"description":"The address to add to the waitlist."},"source":{"type":"string","maxLength":64,"description":"Where the signup came from, e.g. \"landing:closing\"."}}}}}},"responses":{"200":{"description":"The email is on the list (or already was).","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean","const":true}}}}}},"400":{"description":"The body was not JSON or the email is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"geckoKey":{"type":"http","scheme":"bearer","description":"The Gecko key: the bearer credential for GATED surfaces on the hosted MCP server (mcp.geckovision.tech) - not required by any operation in this spec, which is anonymous. Permissions are SCOPED PER SURFACE and deny-by-default: a key opens only the surfaces its account was granted (one named grant per surface, e.g. a paid data surface), never the host. Mint one self-serve: POST /auth/login/start with your email, then /auth/login/verify with the emailed code (documented at /auth.md). There is no OAuth authorization server; scope names are the surface names listed by the host's list_surfaces tool."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Any client-chosen key for retries. Comprehension is read-only and naturally idempotent: the same input always yields the same result and writes nothing, so a retry with or without this header never duplicates work.","schema":{"type":"string","maxLength":255}}},"schemas":{"Error":{"type":"object","required":["error"],"description":"Every error this API returns is structured JSON, never an HTML page.","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. \"invalid-body\", \"upstream-unreachable\"."},"message":{"type":"string","description":"Human-and-agent-readable explanation."},"hint":{"type":"string","description":"What to change before retrying."}}}}},"ComprehendResult":{"type":"object","description":"Preview of a comprehended API surface. Fields are present when known.","properties":{"name":{"type":"string","description":"The surface's name."},"description":{"type":"string"},"op_count":{"type":"integer","description":"Operations found in the source spec."},"usable_tool_count":{"type":"integer","description":"Tools generated and considered callable."},"tools":{"type":"array","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"summary":{"type":"string"}}}},"quarantined":{"type":"boolean","description":"True when the ingested content tripped the anti-poisoning quarantine."},"warnings":{"type":"array","items":{"type":"string"}},"next_steps":{"type":"object","description":"Exact commands to start using the surface.","properties":{"self_host":{"type":"string"},"claude_mcp_add":{"type":"string"},"mcp_json":{"type":"string"}}}}}}}}