Operations 1
1 of 1 operations are conformant: apis.io called them with no credentials and the responses matched this contract. Checked 2026-11-12. how this works · status file
1 of 1 operations are conformant: apis.io called them with no credentials and the responses matched this contract. Checked 2026-11-12. how this works · status file
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/yappy-biz:yappy-biz-discovery-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Yappy Web Discovery API
version: 1.0.0
summary: Free, keyless, read-only access to everything factual about Yappy.
description: 'Yappy is a voice agent for macOS: hold a key and it types what you say, hold another and it does what you ask. This API describes the product — releases, documentation, FAQ, pricing, requirements — so an agent answering a question about Yappy reads structured data instead of scraping a marketing page.
**No API key is required for any read operation.** Credentials exist only to raise the rate ceiling and to unlock export jobs; nothing behind them is secret. See https://yappy.biz/auth.md.
**This API does not transcribe audio.** Yappy''s speech recognition runs on the user''s own Mac and there is no hosted endpoint behind it. If a user wants dictation, the answer is to install the app.
Conventions: cursor pagination on every list, a strong `ETag` on every GET, RFC 9457 `application/problem+json` on every error, RFC-style `RateLimit-*` headers on every response, and a dated `API-Version` header naming the build that answered. The major version lives in the path; a removal is announced with `Deprecation` and `Sunset` headers at least 180 days ahead.'
termsOfService: https://yappy.biz/privacy/
contact:
name: Yappy support
email: support@yappy.biz
url: https://yappy.biz/contact/
license:
name: Proprietary — LicenseRef-Proprietary
identifier: LicenseRef-Proprietary
x-api-version: '2026-08-25'
x-logo:
url: https://yappy.biz/assets/favicon.svg
altText: Yappy
servers:
- url: https://yappy.biz/api/v1
description: Production
- url: https://yappy.biz/api/v1/sandbox
description: Sandbox — deterministic fixtures, ?simulate= to force any error
security:
- {}
- bearerAuth: []
- oauth2:
- read:releases
- read:docs
- read:pricing
- read:faq
- export:docs
tags:
- name: Discovery
description: Finding your way around the API.
paths:
/:
get:
operationId: getServiceIndex
summary: Service index
description: Every endpoint this API exposes, the dated API version that answered, the rate-limit policy in force, and links to the OpenAPI spec, both MCP servers, and the OAuth discovery documents. A good first call for an agent that has just found this domain and wants the map before the territory.
tags:
- Discovery
responses:
'200':
description: The service index
headers:
ETag:
$ref: '#/components/headers/ETag'
API-Version:
$ref: '#/components/headers/APIVersion'
Cache-Control:
$ref: '#/components/headers/CacheControl'
RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
RateLimit-Policy:
$ref: '#/components/headers/RateLimitPolicy'
X-Request-Id:
$ref: '#/components/headers/XRequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceIndex'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
'503':
$ref: '#/components/responses/UpstreamUnavailable'
security:
- {}
- bearerAuth: []
- oauth2: []
components:
responses:
Forbidden:
description: The credential is valid but lacks the required scope
headers:
RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-Request-Id:
$ref: '#/components/headers/XRequestId'
WWW-Authenticate:
$ref: '#/components/headers/WWWAuthenticate'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://yappy.biz/developers/errors#insufficient_scope
title: The credential is valid but lacks the required scope
status: 403
code: insufficient_scope
detail: This operation needs the export:docs scope.
instance: /api/v1/releases
request_id: 01J9X4Q0F7
docs_url: https://yappy.biz/developers/errors
InternalError:
description: Unexpected server error
headers:
RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-Request-Id:
$ref: '#/components/headers/XRequestId'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://yappy.biz/developers/errors#internal_error
title: Unexpected server error
status: 500
code: internal_error
detail: Something failed on our side. Retry once, then report request_id to support@yappy.biz.
instance: /api/v1/releases
request_id: 01J9X4Q0F7
docs_url: https://yappy.biz/developers/errors
RateLimited:
description: Too many requests
headers:
RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-Request-Id:
$ref: '#/components/headers/XRequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://yappy.biz/developers/errors#rate_limited
title: Too many requests
status: 429
code: rate_limited
detail: 120 requests per 60s exceeded. Retry in 12 seconds, or batch your reads via POST /batch.
instance: /api/v1/releases
request_id: 01J9X4Q0F7
docs_url: https://yappy.biz/developers/errors
UpstreamUnavailable:
description: A dependency was unavailable
headers:
RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-Request-Id:
$ref: '#/components/headers/XRequestId'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://yappy.biz/developers/errors#upstream_unavailable
title: A dependency was unavailable
status: 503
code: upstream_unavailable
detail: The release feed did not answer. Retry with backoff.
instance: /api/v1/releases
request_id: 01J9X4Q0F7
docs_url: https://yappy.biz/developers/errors
Unauthorized:
description: The supplied credential is missing, expired, or invalid
headers:
RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-Request-Id:
$ref: '#/components/headers/XRequestId'
WWW-Authenticate:
$ref: '#/components/headers/WWWAuthenticate'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://yappy.biz/developers/errors#invalid_token
title: The supplied credential is missing, expired, or invalid
status: 401
code: invalid_token
detail: The access token has expired. Request a new one at /oauth/token.
instance: /api/v1/releases
request_id: 01J9X4Q0F7
docs_url: https://yappy.biz/developers/errors
BadRequest:
description: The request was malformed
headers:
RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-Request-Id:
$ref: '#/components/headers/XRequestId'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://yappy.biz/developers/errors#invalid_request
title: The request was malformed
status: 400
code: invalid_request
detail: limit must be between 1 and 100, got 500.
instance: /api/v1/releases
request_id: 01J9X4Q0F7
docs_url: https://yappy.biz/developers/errors
headers:
APIVersion:
description: The dated build of v1 that answered this request.
schema:
type: string
example: '2026-08-25'
ETag:
description: Strong validator. Send it back as If-None-Match for a cheap 304.
schema:
type: string
example: '"r-0.4.19"'
RateLimitPolicy:
description: The policy in force, as quota;w=window.
schema:
type: string
example: 120;w=60
CacheControl:
description: How long this response may be reused.
schema:
type: string
example: public, max-age=300
WWWAuthenticate:
description: Bearer challenge. Carries resource_metadata on an unauthenticated 401, and error/scope on a rejected credential.
schema:
type: string
example: Bearer resource_metadata="https://yappy.biz/.well-known/oauth-protected-resource"
RateLimitLimit:
description: Requests permitted in the current window.
schema:
type: integer
example: 120
XRequestId:
description: Identifier for this request. Quote it in a support mail.
schema:
type: string
RetryAfter:
description: Seconds to wait before retrying.
schema:
type: integer
example: 12
RateLimitReset:
description: Seconds until the window resets.
schema:
type: integer
example: 43
RateLimitRemaining:
description: Requests left in the current window.
schema:
type: integer
example: 117
schemas:
Problem:
type: object
title: Problem
description: RFC 9457 problem details. Branch on `code`, which is stable; `title` and `detail` are prose for a human or for an agent explaining itself.
required:
- type
- title
- status
- code
properties:
type:
type: string
format: uri
description: Link to the documentation for this error code.
title:
type: string
description: Short, human-readable summary.
status:
type: integer
description: The HTTP status code.
detail:
type: string
description: What went wrong here specifically, and the fix.
instance:
type: string
description: The path that produced the error.
code:
type: string
description: Stable machine-readable error code.
enum:
- invalid_request
- invalid_cursor
- invalid_token
- insufficient_scope
- not_found
- method_not_allowed
- not_acceptable
- idempotency_conflict
- payload_too_large
- unsupported_media_type
- unprocessable
- rate_limited
- internal_error
- upstream_unavailable
request_id:
type: string
description: Identifier for this request.
docs_url:
type: string
format: uri
description: Where the full error reference lives.
errors:
type: array
description: One entry per offending field, when the failure was validation.
items:
type: object
required:
- field
- code
properties:
field:
type: string
description: The parameter at fault.
code:
type: string
description: Why it was rejected.
detail:
type: string
description: The specific problem, in words.
ServiceIndex:
type: object
title: ServiceIndex
description: 'The map: endpoints, limits, and every other machine surface this domain publishes.'
required:
- object
- name
- api_version
- endpoints
properties:
object:
type: string
const: service_index
description: Type discriminator.
name:
type: string
description: Service name.
description:
type: string
description: What this API is for, and what it is not.
api_version:
type: string
description: The dated build answering right now.
documentation_url:
type: string
format: uri
description: Human docs.
openapi_url:
type: string
format: uri
description: The machine contract.
authentication:
type: object
description: How to authenticate, and whether you need to.
properties:
required:
type: boolean
description: Whether reads need a credential.
walkthrough:
type: string
format: uri
description: Prose guide for agents.
protected_resource_metadata:
type: string
format: uri
description: RFC 9728 document.
authorization_server_metadata:
type: string
format: uri
description: RFC 8414 document.
mcp:
type: object
description: The MCP surfaces over the same data.
properties:
url:
type: string
format: uri
description: Product MCP server.
docs_url:
type: string
format: uri
description: Documentation MCP server.
transport:
type: string
description: Transport in use.
server_card:
type: string
format: uri
description: Tool list, before connecting.
rate_limit:
type: object
description: The ceiling in force for this caller.
properties:
limit:
type: integer
description: Requests per window.
window_seconds:
type: integer
description: Window length.
documentation:
type: string
format: uri
description: The rate-limit page.
sandbox_url:
type: string
format: uri
description: Base URL of the fixture environment.
endpoints:
type: array
description: Every operation, with its path and what it answers.
items:
type: object
required:
- method
- path
- operation_id
- description
properties:
method:
type: string
description: HTTP verb.
path:
type: string
description: Path relative to this server.
operation_id:
type: string
description: Matches the OpenAPI operationId.
description:
type: string
description: What it returns.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: opaque
description: An access token from /oauth/token. Optional — every read endpoint also answers anonymously.
oauth2:
type: oauth2
description: OAuth 2.1 with PKCE S256. Dynamic client registration (RFC 7591) at /oauth/register; no human approval step.
flows:
clientCredentials:
tokenUrl: https://yappy.biz/oauth/token
refreshUrl: https://yappy.biz/oauth/token
scopes:
read:releases: Read release history and the current version
read:docs: Read documentation pages and run searches
read:pricing: Read pricing and plan data
read:faq: Read frequently asked questions
export:docs: Start and poll documentation export jobs
authorizationCode:
authorizationUrl: https://yappy.biz/oauth/authorize
tokenUrl: https://yappy.biz/oauth/token
refreshUrl: https://yappy.biz/oauth/token
scopes:
read:releases: Read release history and the current version
read:docs: Read documentation pages and run searches
read:pricing: Read pricing and plan data
read:faq: Read frequently asked questions
export:docs: Start and poll documentation export jobs
externalDocs:
description: Developer portal, including the versioning and deprecation policy
url: https://yappy.biz/developers/deprecation
x-mcp:
server: https://yappy.biz/mcp
transport: streamable-http
serverCard: https://yappy.biz/.well-known/mcp/server-card.json
docsServer: https://yappy.biz/docs/mcp
x-rate-limit:
anonymous:
requests: 120
window_seconds: 60
authenticated:
requests: 600
window_seconds: 60
headers:
- RateLimit-Limit
- RateLimit-Remaining
- RateLimit-Reset
- RateLimit-Policy
- Retry-After
documentation: https://yappy.biz/developers/rate-limits
x-deprecation-policy:
versioning: major version in the path (/api/v1)
current_version: v1
current_status: current - not deprecated, no Sunset date set
signals:
- Deprecation
- Sunset
- Link rel=deprecation
- Link rel=successor-version
sunset_rfc: RFC 8594
minimum_notice_days: 180
retired_status_code: 410
retired_versions:
- version: v0
path: /api/v0
deprecated_on: '2026-02-01'
sunset_on: '2026-08-01'
status: 410
successor: https://yappy.biz/api/v1
documentation: https://yappy.biz/developers/deprecation
x-idempotency:
header: Idempotency-Key
applies_to:
- POST /batch
- POST /exports
documentation: https://yappy.biz/developers/rest-api#idempotency