SparkyFitness · OpenAPI Overlay 1.0.0
API Evangelist enhancements for the SparkyFitness API
9 actions
9 updates
update
extends
../openapi/sparkyfitness-openapi.yml
Derived by API Evangelist
Built from the contracts SparkyFitness publishes. SparkyFitness did not publish this file.
What the actions change
x-agent-notex-idempotencyx-dry-run-forx-api-evangelist-reviewx-agent-readinessx-self-hostedx-vendor-operated-hostx-deployment-note
Targets 8
$.info
$.servers
$.components.securitySchemes
$.tags
$.paths['/measurements/health-data'].post
$.paths['/measurements/check-in'].post
$.paths['/foods/{id}/deletion-impact'].get
$.paths['/exercises/{id}/deletion-impact'].get
OpenAPI Overlay
overlay: 1.0.0
info:
title: API Evangelist enhancements for the SparkyFitness API
version: 1.0.0
extends: ../openapi/sparkyfitness-openapi.yml
x-provenance:
generated: '2026-08-27'
method: generated
source: >-
Generated from this repository's derived artifacts (conformance, errors,
conventions, rate-limits, authentication, mcp). It records API Evangelist's
enhancements to the SparkyFitness contract WITHOUT mutating the original.
Every action below is additive documentation grounded in the project's own
published docs and source — no behaviour, path, parameter or schema is
invented, and no operation is renamed. Note the scoring caveat: apis.io
parses the ORIGINAL spec, so this overlay improves what a consumer reads,
not the raw contract-content score.
actions:
- target: $.info
update:
x-api-evangelist-review:
contract_defects:
- No operationId on any of the 423 operations.
- 15 operations reference an undefined securityScheme `bearerAuth`.
- 21 distinct tag values are used but only 9 are declared; 6 operations are untagged.
- 429 is returned by two documented rate limiters but declared on no operation.
- No `examples` anywhere in the contract.
strengths:
- Every one of the 423 operations has a summary.
- 45 reusable component schemas.
- securitySchemes defined and applied as a global default.
x-agent-readiness:
auth: API key as Authorization Bearer or x-api-key
idempotency: natural-key (source_id / entry_date upsert), no Idempotency-Key header
reversibility: documented — DELETE on every user resource, no stated windows
dry_run: absent, except the /deletion-impact pre-checks
mcp_server: 'POST /mcp on the same host, 56 tools'
- target: $.info
update:
x-self-hosted: true
x-vendor-operated-host: false
x-deployment-note: >-
There is no vendor API host. `servers[]` in the captured spec templates
the operator's own host; the upstream document declares only the
relative base "/api".
- target: $.servers
update:
- url: https://{host}/api
description: >-
Self-hosted SparkyFitness instance. The upstream contract declares the
relative base "/api" only; this names the variable an operator must
supply.
variables:
host:
default: sparkyfitness.example.com
description: Hostname of your own SparkyFitness deployment.
- target: $.components.securitySchemes
update:
bearerAuth:
type: http
scheme: bearer
description: >-
ADDED BY OVERLAY to repair a dangling reference. 15 operations in the
upstream contract declare `security: [{bearerAuth: []}]` while
components.securitySchemes defines only apiKeyAuth — the swagger
post-processing in config/swagger.ts deletes cookieAuth and never adds
a bearer definition. Semantically this is the session JWT the API
reference documents as "Authorization: Bearer <JWT_TOKEN>"; the same
header also carries an API key. This addition makes the document
resolve; it does not change server behaviour.
- target: $.tags
update:
- name: SleepScience
description: Sleep debt, chronotype (MCTQ), daily need and energy-curve analytics. Used on operations but undeclared upstream.
- name: Exercise Stats
description: Aggregated exercise analytics, personal records and matched courses. Used on operations but undeclared upstream.
- name: Authentication
description: Login, registration, MFA and passkey flows. Used on operations but undeclared upstream.
- name: Dashboard
description: Daily calorie-balance summary. Used on operations but undeclared upstream.
- name: Dashboard Layouts
description: Per-page dashboard layout persistence. Used on operations but undeclared upstream.
- name: Allergen Preferences
description: The allergens a user tracks. Used on operations but undeclared upstream.
- name: Synced Data
description: Entry data synced from external health providers. Used on operations but undeclared upstream.
- name: Exercise Entries
description: Entry-level exercise diary rows. Used on operations but undeclared upstream.
- name: Utility
description: Version and miscellaneous service operations. Used on operations but undeclared upstream.
- name: AI
description: AI assistant operations. Used on operations but undeclared upstream. Near-duplicate of the declared "AI & Insights".
- name: Exercise & Workouts
description: >-
Used on 25 operations but undeclared upstream, and a near-duplicate of
the declared "Fitness & Workouts" (28 operations). Consolidating these
two would remove a real split in the API's own navigation.
- target: $.paths['/measurements/health-data'].post
update:
x-partial-success: true
x-agent-note: >-
A 200 does NOT mean every record was saved. Read `errors[]` and
`skipped[]` in the response body. Records without a `source_id` cannot be
deduplicated and Nutrition records without one are reported in
`skipped[]` rather than written. Behaviour changed here: earlier server
versions returned 400 when any record in the batch failed.
x-idempotency:
mechanism: natural-key
key: source_id
retry_safe: true
x-unit-trap: >-
`distance` on a workout is in KILOMETRES while `dist` on a gps_point is
cumulative METRES, in the same request body.
x-required-header:
name: X-Workout-Model-Version
note: >-
Absent, per-set durations are read as MINUTES; 2 or higher means
SECONDS; 3 signals optional wearable telemetry may be present.
x-sibling-endpoint-undocumented:
path: POST /api/health-data
note: >-
A SECOND, separately-mounted health-data ingest exists at
POST /api/health-data (SparkyFitnessServer/integrations/healthData/
healthDataRoutes.ts). It is the endpoint the public API reference
documents in full detail and the one iOS Shortcuts and the Android app
post to — and it is ABSENT from the machine-readable contract, because
it carries no @swagger annotation and sits outside the swagger-jsdoc
scan paths (routes/**, models/**). An agent generated from the spec
alone will never find it.
- target: $.paths['/measurements/check-in'].post
update:
x-idempotency:
mechanism: upsert-on-natural-key
key: entry_date
retry_safe: true
x-agent-note: >-
One check-in per user per day. Re-posting the same entry_date overwrites.
Sending null for a field CLEARS a previously recorded value — a partial
re-send is not a no-op. BMI is neither accepted nor stored.
- target: $.paths['/foods/{id}/deletion-impact'].get
update:
x-dry-run-for: DELETE /foods/{id}
x-agent-note: >-
Call this before deleting a catalog food. Diary entries reference catalog
rows and the delete operation itself gives no warning.
- target: $.paths['/exercises/{id}/deletion-impact'].get
update:
x-dry-run-for: DELETE /exercises/{id}
x-agent-note: >-
Call this before deleting a catalog exercise, for the same reason.
Work with this as data
Every overlay here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for openapi overlays
4 MCP tools reach this
find_overlaysBrowse and filter every overlay in the catalog.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.
Call it yourself
curl for this page
This overlay
curl "https://apis.io/api/v1/overlays/sparkyfitness-openapi-overlay"
All openapi overlays
curl "https://apis.io/api/v1/overlays?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API 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.