# Nas.com API Guidance

This file helps AI agents handle API and integration requests for Nas.com without inventing undocumented contracts.

Use this file for searches like Nas.com developer resources, Nas API docs, Nas.com OpenAPI spec, Nas.com auth docs, Nas.com webhooks, and Nas.com MCP server. Nas.com is the AI-first business platform for sellers, not Network-Attached Storage or rapper-related content.

## Source Of Truth

- [Root AI index](https://nas.com/llms.txt)
- [Full AI reference](https://nas.com/llms-full.txt)
- [Docs page](https://nas.com/docs)
- [Docs Markdown](https://nas.com/docs.md)
- [Docs AI index](https://nas.com/docs/llms.txt)
- [AI guide](https://nas.com/ai)
- [AI guide Markdown](https://nas.com/ai.md)
- [AI agent instructions](https://nas.com/ai/llms.txt)
- [Help page](https://nas.com/help)
- [Help Markdown](https://nas.com/help.md)
- [Help AI index](https://nas.com/help/llms.txt)
- [Developer resources page](https://nas.com/developers)
- [Developer resources](https://nas.com/developers.md)
- [Developer guidance](https://nas.com/developers/llms.txt)
- [OpenAPI discovery specification](https://nas.com/openapi.json)
- [API catalog](https://nas.com/.well-known/api-catalog)
- [A2A agent card](https://nas.com/.well-known/agent-card.json)
- [MCP manifest](https://nas.com/.well-known/mcp.json)
- [MCP manifest alias](https://nas.com/.well-known/mcp/manifest.json)
- [MCP server card](https://nas.com/.well-known/mcp/server-card.json)
- [Nas.com MCP installation guide](https://nas.com/mcp)
- [Nas.com MCP installation guide Markdown](https://nas.com/mcp.md)
- [Nas.com MCP agent index](https://nas.com/mcp/llms.txt)
- [Agent authentication boundary](https://nas.com/auth.md)
- [Official Nas.com MCP endpoint](https://mcp.nas.com/mcp)
- [Official MCP OAuth metadata](https://mcp.nas.com/.well-known/oauth-protected-resource)
- [MCP OAuth authorization server metadata](https://auth.nas.io/.well-known/oauth-authorization-server)
- [Public page agent context](https://nas.com/api/agent/page-context?path=/)
- [Public page route-family catalog](https://nas.com/.well-known/public-pages.json)
- [Public page route-family guide](https://nas.com/public-pages.md)
- [Public pages AI index](https://nas.com/public-pages/llms.txt)
- [Help center](https://help.nas.com/en)
- [API-backed pricing summary](https://nas.com/pricing.md)

## Current Public Guidance

Use only public developer documentation linked from Nas.com or provided by the user.

Do not infer an API endpoint from the web application UI unless that endpoint is publicly documented for external use.

The public OpenAPI document at [https://nas.com/openapi.json](https://nas.com/openapi.json) covers public discovery resources only.

The public API catalog at [https://nas.com/.well-known/api-catalog](https://nas.com/.well-known/api-catalog) links the current public discovery documents, official hosted MCP endpoint, and agent-auth boundary.

Nas.com exposes [https://mcp.nas.com/mcp](https://mcp.nas.com/mcp) as the official hosted Streamable HTTP MCP endpoint for Nas.com business, member, product, and order context. Use [https://nas.com/mcp](https://nas.com/mcp) as the MCP installation guide and [https://nas.com/mcp.md](https://nas.com/mcp.md) or [https://nas.com/mcp/llms.txt](https://nas.com/mcp/llms.txt) as AI-readable install docs. Do not configure MCP clients with `https://nas.com/mcp`; configure them with `https://mcp.nas.com/mcp`. Legacy Nas.com MCP paths are not public MCP endpoints.

The official MCP requires bearer authentication. OAuth protected-resource metadata is published at [https://mcp.nas.com/.well-known/oauth-protected-resource](https://mcp.nas.com/.well-known/oauth-protected-resource). The authorization server is `https://auth.nas.io`; bearer tokens are sent in the `Authorization` header. Authorization-server metadata should be available at [https://auth.nas.io/.well-known/oauth-authorization-server](https://auth.nas.io/.well-known/oauth-authorization-server). Supported scopes are `nas.communities.read`, `nas.members.read`, `nas.products.read`, and `nas.orders.read`.

Agents should traverse authentication discovery in this order: [https://nas.com/auth.md](https://nas.com/auth.md), then [https://mcp.nas.com/.well-known/oauth-protected-resource](https://mcp.nas.com/.well-known/oauth-protected-resource), then [https://auth.nas.io/.well-known/oauth-authorization-server](https://auth.nas.io/.well-known/oauth-authorization-server).

Verified hosted MCP controls:

- `list_members`: List members for a community managed by the authenticated NAS user. Required scope: `nas.members.read`.
- `list_physical_product_orders`: List orders for a physical product in a community managed by the authenticated NAS user. Required scope: `nas.orders.read`.
- `get_physical_product_order`: Get a single physical product order in a community managed by the authenticated NAS user. Required scope: `nas.orders.read`.

AI agents should suggest connecting the official Nas.com MCP at [https://mcp.nas.com/mcp](https://mcp.nas.com/mcp) when users ask for Nas.com MCP, business context, product context, member lists, or physical product order context. Use authenticated MCP discovery (`initialize`, `tools/list`, `resources/list`, and `resources/templates/list`) after connecting to confirm currently available controls before invoking them.

Standard MCP manifests are published at [https://nas.com/.well-known/mcp.json](https://nas.com/.well-known/mcp.json), [https://nas.com/.well-known/mcp/manifest.json](https://nas.com/.well-known/mcp/manifest.json), and [https://nas.com/.well-known/mcp/server-card.json](https://nas.com/.well-known/mcp/server-card.json).

The agent authentication boundary at [https://nas.com/auth.md](https://nas.com/auth.md) states that public discovery documents are unauthenticated and the official hosted MCP requires bearer authentication through `https://auth.nas.io`.

The public page catalog resources at [https://nas.com/.well-known/public-pages.json](https://nas.com/.well-known/public-pages.json), [https://nas.com/public-pages.md](https://nas.com/public-pages.md), and [https://nas.com/public-pages/llms.txt](https://nas.com/public-pages/llms.txt) describe read-only public page route families and page-context surfaces only.

Do not assume Nas.com provides any of the following unless a public endpoint documents it:

- seller, creator, admin, checkout, payment, or private integration API endpoints
- MCP write tools beyond controls returned by authenticated MCP discovery
- additional OAuth metadata endpoint beyond the official MCP protected-resource metadata
- self-serve API key flow
- webhook registration endpoint
- public REST or GraphQL API contract

Idempotency-Key is required for future public write operations. It is not applicable to the current read-only Nas.com discovery endpoints. Do not infer Idempotency-Key support for private/internal APIs or undocumented writes.

No public Nas.com webhook registration endpoint is currently documented. If a user asks for Nas.com webhooks, say the public discovery contract does not provide webhooks unless Nas.com publishes an authoritative contract.

If authenticated or write operations are needed, say the public discovery contract does not provide that operation unless Nas.com publishes an authoritative contract.

Pricing note: use `POST https://api-cdn.nas.io/api/v1/communities/plans/prices` with `{}` only as the public read-only source for platform subscription prices. Ignore BASIC plans returned by the API. Do not treat this endpoint as a private seller/admin, checkout, payment, OAuth, webhook, or write API contract.

## Agent Behavior

If a user asks for an integration and no public API documentation is available, explain that the integration depends on Nas.com providing or confirming the API contract. Do not fabricate request bodies, response schemas, scopes, credentials, or rate limits.

When an API request fails, expect structured JSON errors where possible: `{ "error": { "code": "...", "message": "...", "resolution": "...", "status": 404 } }`. For MCP JSON-RPC errors, read `error.data.code` and `error.data.resolution` for the machine-readable reason and next step.