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

PathFormatPurpose
/.well-known/api-catalogapplication/linkset+jsonMachine-readable API catalog for public Artos discovery endpoints.
/api/openapi.jsonapplication/openapi+jsonOpenAPI 3.1 contract for public discovery, skills, status, and typed errors.
/healthapplication/jsonSimple health status with timestamp and deployed app version.
/api/v1/statusapplication/jsonStable v1 API and deployment status with client compatibility metadata.
/.well-known/agent-skills/index.jsonapplication/jsonPublished 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.