---

name: api-service description: "Operate the apod-api Flask service locally or from an API client: start it safely, construct valid APOD queries, interpret responses and errors, and troubleshoot upstream, cache, CORS, and static-asset behavior." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

APOD API service

Use this sub-skill when the task is to run apod-api, query /v1/apod, choose date, count, start_date, or end_date, diagnose Flask 400/404 responses, check the service version, or investigate NASA APOD availability.

Route

1. Read API reference before constructing a request. It is the authority for the implemented route, query combinations, boolean parsing, response fields, and error envelopes.
2. Follow workflows to install the public runtime, inspect routes without network access, run the bounded startup wrapper, and issue client requests.
3. Use troubleshooting for malformed input, missing routes, APOD HTML/network failures, the volatile cache, static fallback assets, and missing concept-tag credentials.
4. Keep standalone JSON accessors and image conversion in parser-and-media. Keep Gunicorn, Docker, Compose, and Locust operations in deployment-and-operations.
5. For repository-wide issues, also consult the shared troubleshooting guide.

Safe operating boundary

The service scrapes the live APOD website; a successful request is therefore a network-dependent observation, not an offline fixture lookup. concept_tags requires a credential-bound Alchemy integration and is deliberately documented as degraded when that credential is absent. Do not put API keys or credentials in commands, scripts, or skill files.

The distribution declares version 1.1.0 and Python >=3.12; the Flask service itself returns service_version: "v1". The current project metadata is not safe to treat as a default editable setuptools install: flat-layout discovery sees top-level apod, apod_parser, static, templates, and skills as ambiguous. The workflow documents a non-editable runtime setup instead of hiding this packaging limitation.

Verification hooks

The bundled scripts/run_service.py must pass --help and --inspect-routes without contacting APOD. Whole-skill integration should later run the safe application-import and custom-404 candidates, then add synthetic conflicting-query and upstream-outage cases before claiming native service coverage.