yappy-biz Batch API
Many reads, one request, one unit of rate limit.
Many reads, one request, one unit of rate limit.
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-batch-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 Batch 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: Batch
description: Many reads, one request, one unit of rate limit.
paths:
/batch:
post:
operationId: createBatch
summary: Run up to 20 reads in one request
description: Bundle up to twenty GET operations into a single round trip that costs one unit of rate limit rather than twenty. Each result carries the id you supplied, its own HTTP status, and its body; one failing operation returns its problem document in that entry and leaves the rest untouched.
tags:
- Batch
responses:
'200':
description: Per-operation results
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'
Idempotency-Key:
$ref: '#/components/headers/IdempotencyKey'
content:
application/json:
schema:
$ref: '#/components/schemas/BatchResponse'
'413':
$ref: '#/components/responses/PayloadTooLarge'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
'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'
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
description: The operations to run.
content:
application/json:
schema:
$ref: '#/components/schemas/BatchRequest'
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
UnsupportedMediaType:
description: The body was not application/json
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#unsupported_media_type
title: The body was not application/json
status: 415
code: unsupported_media_type
detail: POST bodies must be application/json.
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
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
PayloadTooLarge:
description: The request body was too large
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#payload_too_large
title: The request body was too large
status: 413
code: payload_too_large
detail: A batch accepts at most 20 operations; 34 were supplied.
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
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
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
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"
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
CacheControl:
description: How long this response may be reused.
schema:
type: string
example: public, max-age=300
RateLimitLimit:
description: Requests permitted in the current window.
schema:
type: integer
example: 120
IdempotencyKey:
description: Echo of the Idempotency-Key you supplied.
schema:
type: string
schemas:
BatchRequest:
type: object
title: BatchRequest
description: Up to twenty read operations to run in one request.
required:
- operations
properties:
operations:
type: array
minItems: 1
maxItems: 20
description: The operations, run independently of each other.
items:
type: object
required:
- id
- method
- path
properties:
id:
type: string
maxLength: 64
description: Your label for this operation, echoed back.
method:
type: string
enum:
- GET
description: Only GET is accepted inside a batch.
path:
type: string
maxLength: 512
description: A path relative to /api/v1, query string included.
examples:
- /releases/latest
- /faq?limit=2
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.
BatchResponse:
type: object
title: BatchResponse
description: One entry per operation, in the order supplied. Check each status; the envelope is 200 even when an operation failed.
required:
- object
- results
properties:
object:
type: string
const: batch
description: Type discriminator.
results:
type: array
description: Per-operation outcomes.
items:
type: object
required:
- id
- status
- body
properties:
id:
type: string
description: The label you supplied.
status:
type: integer
description: HTTP status for this operation.
body:
description: The operation's response body, or its problem document.
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
required: false
description: A client-chosen key that makes a retry return the original result instead of starting a second job. Echoed back on the response.
schema:
type: string
maxLength: 128
example: docs-export-1
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