---
title: "Rafmennt API and developer documentation"
description: "Quickstart, anonymous public API, MCP, NLWeb, pagination, errors and API versioning."
canonical: "https://www.rafmennt.is/developers"
---

# Rafmennt API and developer documentation

Read published information about electrical-trades education in Iceland: courses, upcoming groups, events, fees and journeyman examinations. Most source content is Icelandic; search with topic keywords such as ljósleiðarar or sveinspróf.

Access is free and anonymous. No account, API key or authentication setup is needed. These interfaces only search, list and read public content. They do not access the CMS, drafts, personal records, registrations or payments.

[OpenAPI specification](https://www.rafmennt.is/agent/openapi.json) · [Content index](https://www.rafmennt.is/llms.txt) · [Agent instructions](https://www.rafmennt.is/agent-instructions.md) · [Access guidance](https://www.rafmennt.is/auth.md)

## Quickstart

Search for a topic, then use a returned path to read its canonical page. The following requests are safe to try on the live public service.

```bash
curl -sS 'https://www.rafmennt.is/api/v1/search?q=raf&limit=5'
```

```bash
curl -sS 'https://www.rafmennt.is/api/v1/page?path=/endurmenntun/verdskra&format=markdown'
```

Use the canonical source URL when citing a result. Course dates, availability, eligibility and membership-based prices can change; read the selected course page before making a recommendation. The [pricing document](https://www.rafmennt.is/pricing.md) contains the published fee table.

## Public REST API

[API directory](https://www.rafmennt.is/api/v1). All REST operations use GET; HEAD and cross-origin OPTIONS are supported.

- [/api/v1/search](https://www.rafmennt.is/api/v1/search?q=raf) — keyword search with q.
- [/api/v1/courses](https://www.rafmennt.is/api/v1/courses) — upcoming groups, filtered by q, location, from and to.
- [/api/v1/events](https://www.rafmennt.is/api/v1/events) — upcoming events with the same filters.
- [/api/v1/page](https://www.rafmennt.is/api/v1/page?path=/hafa-samband) — metadata for path; add format=markdown to read the page.

Dates use YYYY-MM-DD. List endpoints accept limit (1–40, default 40) and cursor. Responses contain results, total, pageSize and nextCursor. Follow the HTTP Link with rel="next", or pass nextCursor with the same filters. A null nextCursor marks the last page. A stale cursor returns INVALID\_PAGINATION; restart without cursor.

```json
{"results": [], "total": 0, "pageSize": 40, "nextCursor": null}
```

For bulk reference data, use the [Schema Feeds index](https://www.rafmennt.is/schemamap.xml) and JSON Lines feeds for [courses](https://www.rafmennt.is/feeds/course.jsonl), [events](https://www.rafmennt.is/feeds/event.jsonl), [pages](https://www.rafmennt.is/feeds/page.jsonl) and [articles](https://www.rafmennt.is/feeds/article.jsonl). These contain published Schema.org entities.

## Errors, limits and retries

REST errors use application/problem+json (RFC 9457), with status, code, detail and hint. Invalid filters return 400; unknown or private pages return 404; unsupported methods return 405; temporary service failures return 500.

```json
{
  "type": "about:blank",
  "title": "Not found",
  "status": 404,
  "detail": "The page is unknown or is not published public content.",
  "code": "PAGE_NOT_FOUND",
  "hint": "Use a path returned by public search. Private and CMS pages are unavailable.",
  "instance": "/api/v1/page"
}
```

REST, MCP, A2A and NLWeb share a limit of 120 requests per 60 seconds per IP at each Cloudflare location. RateLimit-Policy describes the quota. Cloudflare does not expose an exact remaining count. On HTTP 429, wait the Retry-After interval (60 seconds). For temporary network or 5xx failures, retry with exponential backoff and jitter. Reading is safe to retry; no operation creates or changes a record.

## MCP and browser agents

Connect an MCP client to [the server described in this card](https://www.rafmennt.is/mcp/server-card), using Streamable HTTP at https://www.rafmennt.is/mcp. Discover the live tools with tools/list: search\_public\_site, find\_courses, list\_upcoming\_events and read\_public\_page. Tool input and output schemas are self-contained; errors carry structured code, message and hint fields.

```json
{
  "mcpServers": {
    "rafmennt-public": {
      "type": "streamable-http",
      "url": "https://www.rafmennt.is/mcp"
    }
  }
}
```

Compatible browsers also receive WebMCP tools on public pages, including open\_public\_page. Support is feature-detected through document.modelContext, with navigator.modelContext as a compatibility fallback. Browser tools are removed when leaving the public site layout. The CMS has no public browsing tools.

[Installable skills with SHA-256 digests](https://www.rafmennt.is/.well-known/agent-skills/index.json) · [Agent Plugin manifest](https://www.rafmennt.is/agent-plugin/plugin.json) · [Resource discovery](https://www.rafmennt.is/.well-known/ard.json) · [A2A card](https://www.rafmennt.is/.well-known/agent-card.json)

## NLWeb search and streaming

NLWeb 0.55 supports keyword retrieval in list mode. POST a JSON query.text and optionally prefer.streaming. JSON responses carry \_meta and typed results, or an application-level failure with an error code. Streaming uses SSE start, result, error and complete events.

```bash
curl -sS 'https://www.rafmennt.is/ask' \
  -H 'Content-Type: application/json' \
  --data '{"query":{"text":"raf"},"prefer":{"mode":"list"}}'
```

```bash
curl -N 'https://www.rafmennt.is/ask?q=raf&streaming=true'
```

Use the canonical origin shown above directly for POST requests. Redirects from another hostname may discard the request body. Generated summaries, personal conversations and autonomous actions are not supported.

## Versioning and testing

REST version 1 lives at /api/v1 and sends the API-Version: 1 response header.

- Existing /agent/search, /agent/courses, /agent/events and /agent/page URLs remain compatible aliases.
- Clients should accept new response fields. Breaking changes will use a new major URL version.
- Before retiring a version, we will publish Deprecation and Sunset headers with at least 90 days notice here.

### Testing

Try the live endpoints for small read-only integration checks. Automated tests use an isolated local database; a separate public sandbox is not available.

Keep queries free of personal data. For a content question the site does not answer, [contact Rafmennt](https://www.rafmennt.is/hafa-samband).

Source: https://www.rafmennt.is/developers