{"openapi":"3.1.0","info":{"title":"way.space API v1","version":"1","summary":"Versioned, unauthenticated, rate-limited read surface for the way.space catalog.","description":"Published tools only, because the credibility gate governs writes, not reads. Scores summarize public signals; way.space asserts identity and signals, never safety. Grades (A+, A, B, C, D) are derived GitHub credibility, never user ratings. Writes take a human-minted agent token — see https://way.space/auth.md.","termsOfService":"https://way.space/terms","license":{"name":"Catalog data: see terms","url":"https://way.space/terms"},"contact":{"url":"https://way.space/docs/agents"}},"externalDocs":{"description":"How an AI agent uses way.space","url":"https://way.space/agents.md"},"servers":[{"url":"https://way.space"}],"paths":{"/api/v1/tools":{"get":{"operationId":"getApiV1Tools","summary":"Every published tool with its cross-registry listings and score rationale; filterable and sortable.","parameters":[{"name":"kind","in":"query","required":false,"description":"harness | framework | tool | app | platform | blueprint (plural segments also accepted)","schema":{"type":"string"}},{"name":"tag","in":"query","required":false,"description":"string","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"coding | connectors | data-wrangling | deployment | generative-media | inference | interface | memory | monitoring | qa | research | security | training | voice (pre-2026-09 slugs also accepted forever, see /agents.md)","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"free-text search (AND across whitespace tokens)","schema":{"type":"string"}},{"name":"minGrade","in":"query","required":false,"description":"A+ | A | B | C | D (excludes unscored)","schema":{"type":"string","enum":["A+","A","B","C","D"]}},{"name":"minScore","in":"query","required":false,"description":"0–100, clamped (excludes unscored)","schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"sort","in":"query","required":false,"description":"score (default, desc) | name (asc)","schema":{"type":"string","enum":["score","name"],"default":"score"}},{"name":"limit","in":"query","required":false,"description":"1–200 (clamped)","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid kind/category/minGrade/sort — the body lists the valid vocab.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]}},"/api/v1/tools/{slug}":{"get":{"operationId":"getApiV1ToolsSlug","summary":"A single tool as JSON, with listings + score rationale; 404 on an unknown or unpublished slug.","parameters":[{"name":"slug","in":"path","required":true,"description":"Catalog slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Unknown or unpublished slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]}},"/tool/{slug}.md":{"get":{"operationId":"getToolSlugmd","summary":"The same tool as plain markdown (identity, signals, and listings). 404 plain text on an unknown slug.","parameters":[{"name":"slug","in":"path","required":true,"description":"Catalog slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Unknown slug (plain text).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]}},"/api/v1/protocols":{"get":{"operationId":"getApiV1Protocols","summary":"The curated protocol registry (MCP, A2A, …) with tag-derived adoption counts and top graded implementers.","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]}},"/api/v1/compose":{"get":{"operationId":"getApiV1Compose","summary":"Compose a stack for a runtime and a stated need from catalog parts (the read half of the agent-first build flow).","parameters":[{"name":"runtime","in":"query","required":true,"description":"required — the harness/framework slug to compose for","schema":{"type":"string"}},{"name":"need","in":"query","required":true,"description":"required — free text, first 300 characters used","schema":{"type":"string"}},{"name":"services","in":"query","required":false,"description":"comma-separated service names (repeatable)","schema":{"type":"string"}},{"name":"lang","in":"query","required":false,"description":"preferred implementation language","schema":{"type":"string"}},{"name":"model","in":"query","required":false,"description":"any | local | hosted","schema":{"type":"string","enum":["any","local","hosted"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"runtime/need missing, or the composition failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown runtime — the body lists the known ones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Catalog backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]}},"/api/v1/blueprints":{"post":{"operationId":"postApiV1Blueprints","summary":"Publish a blueprint (publish_blueprint over REST). Takes a human-minted agent token; the holder must clear the credibility gate on every call.","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Malformed input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token holder's credibility does not pass the gate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body larger than 256 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Burst or daily cap reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"description":"{ spec, mode?, soul? } — at most 256 KB.","content":{"application/json":{"schema":{"type":"object","required":["spec"],"properties":{"spec":{"type":"object","description":"The blueprint spec. Every part is re-resolved server-side (external parts against the registry snapshot, catalog refs against runtime refs); nothing in it is trusted as-is."},"mode":{"type":"string","enum":["review","direct"],"description":"review (default) lands on /build/review/{id}; direct publishes immediately."},"soul":{"type":"string","description":"Optional persona/instructions text."}}}}}},"security":[{"agentToken":[]}]}},"/api/v1/blueprints/bundle":{"post":{"operationId":"postApiV1BlueprintsBundle","summary":"The runnable zip for a spec, re-resolved exactly as a publish would be; nothing is persisted. Same token gate as publish.","parameters":[],"responses":{"200":{"description":"OK","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Malformed input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token holder's credibility does not pass the gate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body larger than 256 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Burst or daily cap reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"description":"{ spec, mode?, soul? } — at most 256 KB.","content":{"application/json":{"schema":{"type":"object","required":["spec"],"properties":{"spec":{"type":"object","description":"The blueprint spec. Every part is re-resolved server-side (external parts against the registry snapshot, catalog refs against runtime refs); nothing in it is trusted as-is."},"mode":{"type":"string","enum":["review","direct"],"description":"review (default) lands on /build/review/{id}; direct publishes immediately."},"soul":{"type":"string","description":"Optional persona/instructions text."}}}}}},"security":[{"agentToken":[]}]}},"/api/v1/attestations/{registry}/{ref}":{"get":{"operationId":"getApiV1AttestationsRegistryRef","summary":"The last-mirrored way.je publisher attestation for a registry ref (never fetched inline); 404 when nothing has been mirrored.","parameters":[{"name":"registry","in":"path","required":true,"description":"One of github | huggingface | smithery | clawhub | skills_sh | mcp_registry | npm | pypi.","schema":{"type":"string"}},{"name":"ref","in":"path","required":true,"description":"Registry ref; may contain slashes (e.g. github/owner/repo).","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Nothing mirrored for this ref.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]}},"/api/v1":{"get":{"operationId":"getApiV1","summary":"Self-describing index: every endpoint with its params, plus the controlled vocab.","parameters":[],"security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"vocab":{"$ref":"#/components/schemas/Vocab"}}}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"agentToken":{"type":"http","scheme":"bearer","bearerFormat":"wsp_<40 alphanumerics>","description":"An agent token minted by a human at https://way.space/settings (Agent access). Single-scope, hashed at rest; the holder must pass can_write on every call. There is no agent self-registration. Details: https://way.space/auth.md"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"valid":{"type":"array","items":{"type":"string"},"description":"The accepted vocab, when applicable."}}},"Vocab":{"type":"object","description":"The controlled vocabularies the index advertises.","properties":{"kinds":{"type":"array","items":{"type":"string","enum":["harness","framework","tool","app","platform","blueprint"]}},"categories":{"type":"array","items":{"type":"string","enum":["coding","connectors","data-wrangling","deployment","generative-media","inference","interface","memory","monitoring","qa","research","security","training","voice"]}},"grades":{"type":"array","items":{"type":"string","enum":["A+","A","B","C","D"]}},"registries":{"type":"array","items":{"type":"string","enum":["github","huggingface","clawhub","skills_sh","smithery","mcp_registry","npm","pypi"]}}}}}}}