# SAMSA.AGENCY public API

Base URL: https://samsa.agency

## Discovery

- [API catalog](https://samsa.agency/.well-known/api-catalog) — RFC 9727 linkset.
- [OpenAPI description](https://samsa.agency/openapi.json) — health and public content endpoints.
- [Capabilities](https://samsa.agency/.well-known/ai-catalog.json) and [skills](https://samsa.agency/.well-known/agent-skills/index.json).
- [Authentication policy](https://samsa.agency/auth.md).

## Health

`GET /api/health` requires no credentials and returns JSON:

```json
{"status":"success","service":"samsa-api","dataDir":".data"}
```

`dataDir` is a relative storage label and may vary by deployment. It is not an accessible resource. Errors use HTTP status codes; availability is not guaranteed.

## Reading site content

Request a public page with `Accept: text/markdown`. For example:

```sh
curl -H 'Accept: text/markdown' https://samsa.agency/en/services
```

HTML is the default. Markdown follows the page language and is generated from the same page during prerendering. Responses vary on `Accept`; Markdown has `Content-Type: text/markdown; charset=utf-8`. Query parameters do not change this published content snapshot. The resources in this document allow GET and HEAD. The health endpoint allows GET.

## Project enquiries and private APIs

Use the [contact page](https://samsa.agency/contact) or [brief](https://samsa.agency/brief) for enquiries. A person reviews and submits the request. Website forms and analytics use internal POST endpoints that are not part of this public API contract.

The administrative API uses staff sessions and is not offered to third-party agents.

## Agent content API and MCP

Register anonymously and obtain a resource-bound OAuth token using [auth.md](https://samsa.agency/auth.md). The only scope is `content.read`; registrations expire after 24 hours and tokens after 15 minutes. Revocation is immediate and persists across restarts.

For REST, request the resource `https://samsa.agency/api/agent` and send `Authorization: Bearer ACCESS_TOKEN`:

- `GET /api/agent/search?q=branding&language=en&limit=10` — search published pages; language is optional (`ru`, `en`, `uz`), limit is 1–20.
- `GET /api/agent/page?path=%2Fen%2Fservices` — retrieve Markdown for an exact published path returned by search.
- `GET /api/agent/resources` — get public resource URLs.

For MCP, request the resource `https://samsa.agency/mcp` and connect using Streamable HTTP at [the MCP endpoint](https://samsa.agency/mcp). See [the current Server Card](https://samsa.agency/mcp/server-card); the legacy discovery alias is [available here](https://samsa.agency/.well-known/mcp/server-card.json). Tools are `search_public_content`, `read_public_page`, and `get_site_resources`, all read-only. Normal MCP initialization and live tool/resource listing are supported; no persistent SSE session is required.

Public clients may also use the discovered authorization-code flow with S256 PKCE and explicit anonymous-content consent. No OIDC ID token, human identity assertion, private data, lead submission, staff session or A2A service is provided. Limits and complete registration, token and revocation requests are documented in auth.md.