API discovery
Artos public discovery endpoints
This page documents the machine-readable endpoints Artos publishes for agent and API discovery. Browsers get HTML by default, while agents can request markdown by sendingAccept: text/markdownto HTML pages.
Authentication and scope
All discovery endpoints listed here use GET and require no authentication, cookies, or API key. They provide public information only. Checkout, orders, account data, and seller changes are not part of this public API. Send shoppers to the current product page to complete a purchase.
Example requests
curl --fail https://artosmarket.com/api/v1/status curl --fail https://artosmarket.com/api/openapi.json curl --fail https://artosmarket.com/llms.txt curl --fail -H 'Accept: text/markdown' 'https://artosmarket.com/search?q=prayer%20rope'
Status returns JSON with status, timestamp, apiVersion, appVersion, and forceReload. Search returns the public page as Markdown, not a JSON product API. Follow its product links and check current availability, price, shipping, and returns. Read agent instructions for best-fit uses.
Command-line tool
The Artos CLI is prepared for publication. An npm installation command will be added here after the package is published. Until then, use the curl examples above. The CLI supports status, catalog, openapi, skills, instructions, feed, docs, search, and product lookup. It requires no account or API key.
Published endpoints
| Path | Format | Purpose |
|---|---|---|
| /.well-known/api-catalog | application/linkset+json | Machine-readable API catalog for public Artos discovery endpoints. |
| /api/openapi.json | application/openapi+json | OpenAPI 3.1 contract for public discovery, skills, status, and typed errors. |
| /health | application/json | Simple health status with timestamp and deployed app version. |
| /api/v1/status | application/json | Stable v1 API and deployment status with client compatibility metadata. |
| /.well-known/agent-skills/index.json | application/json | Published Artos skills index with integrity digests for each SKILL.md file. |
Homepage discovery headers
Link: </>; rel="alternate"; type="text/markdown" Link: </llms.txt>; rel="describedby"; type="text/plain" Link: </.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json" Link: </api/openapi.json>; rel="service-desc"; type="application/openapi+json" Link: </docs/api>; rel="service-doc"; type="text/html"
Errors
Errors from the public discovery endpoints above use RFC 9457 Problem Details with the media type application/problem+json. Unknown API paths and non-JSON failures under /api/* are normalized to the same shape, including code, message, andresolution extensions. Existing JSON errors from other subsystems, including authentication, keep their endpoint-specific schema.
Normalized HTTP status errors: The response keeps its HTTP status and supplies a stable JSON shape even when no more specific Artos error code applies.
INVALID_REQUEST: Correct the request using the published OpenAPI contract.
AUTHENTICATION_REQUIRED: Supply the documented credentials.
ACCESS_DENIED: Use credentials permitted to access the resource.
API_NOT_FOUND: Check the OpenAPI document for a supported path.
METHOD_NOT_ALLOWED: Use a method documented for the requested path.
INTERNAL_SERVER_ERROR: Retry later and contact support if the error continues.
Versioning and deprecation
Stable Artos API resources use major-version URL paths such as/api/v1/. Additive, backward-compatible changes stay within the current major version; breaking changes receive a new major path.
Artos gives at least 180 days notice before retiring a public API resource. Deprecated resources return an RFC 9745Deprecation date and aLink with rel="deprecation". When a retirement date is scheduled, Artos also returns an RFC 8594Sunset HTTP-date.
Notes
These endpoints describe the public discovery surface that exists today. They do not publish placeholder OAuth, MCP, or commerce metadata.
For machine clients, the API catalog is the best entry point. For humans, this documentation page is the easiest place to start.