REST API reference

Query the documentation over plain HTTP/JSON — the same capabilities as the MCP server, for tools that don't speak MCP

Not every tool speaks the Model Context Protocol. For those, the same three capabilities exposed by the MCP server — search, package / page discovery, and full page retrieval — are also available as a plain, read-only REST API returning JSON.

Both surfaces are backed by the same search index and scoring, so a query returns identical results whether it comes from an MCP client or a curl call.

Interactive docs. The API is documented with Scramble and browsable — with a live "Try it" console — at /docs/api. The OpenAPI document itself is served at /docs/api.json.

Conventions

Base URL — https://dev.olacombe.com/api (adapt to your deployment).
Format — all responses are JSON; list endpoints wrap results in a data key.
Read-only — every endpoint is GET; no authentication is required by default.
Rate limit — 60 requests per minute per IP (same as the MCP HTTP transport). Exceeding it returns 429 Too Many Requests.

Endpoints

Method & path	Purpose	MCP equivalent
`GET /api/documentation/search`	Full-text search across every page	`search-documentation`
`GET /api/documentation/packages`	List all documented packages	`list-documentation-packages`
`GET /api/documentation/packages/{package}`	List the pages of one package	`list-documentation-packages`
`GET /api/documentation/pages/{slug}`	Read a full page as Markdown	`get-documentation-page`

The typical flow mirrors the MCP one: search → read the page you need.

Search the documentation

GET /api/documentation/search

Query parameter	Type	Required	Description
`q`	string	yes	The text to search for (2–200 characters).
`package`	string	no	Scope the search to one package, e.g. `oi-laravel-ts`.
`limit`	integer	no	Maximum number of results, 1–50 (default 10).

bash

curl "https://dev.olacombe.com/api/documentation/search?q=watch%20mode&limit=1"

json

{
    "data": [
        {
            "slug": "oi-laravel-ts/advanced/watch-mode",
            "title": "Watch Mode",
            "section": "OI Laravel TypeScript > Advanced",
            "description": "Automatically regenerate interfaces when models change",
            "excerpt": "# Watch Mode\n\nWatch mode monitors your models directory and automatically regenerates the TypeScript file whenever a model file changes. It's designed...",
            "score": 14
        }
    ]
}

Results are ordered by score (highest first). Feed any result's slug to the page endpoint to read it in full.

List documented packages

GET /api/documentation/packages

Takes no parameters. Returns every documented package with its page count.

bash

curl "https://dev.olacombe.com/api/documentation/packages"

json

{
    "data": [
        {
            "slug": "oi-laravel-ts",
            "title": "OI Laravel TypeScript",
            "description": "Generate TypeScript interfaces from your Eloquent models",
            "pages": 8
        }
    ]
}

List the pages of a package

GET /api/documentation/packages/{package}

Path parameter	Type	Description
`package`	string	A package slug from the list above, e.g. `oi-laravel-ts`.

bash

curl "https://dev.olacombe.com/api/documentation/packages/oi-laravel-ts"

json

{
    "data": [
        {
            "slug": "oi-laravel-ts/getting-started",
            "title": "Introduction",
            "section": "OI Laravel TypeScript > Getting Started"
        }
    ],
    "package": "oi-laravel-ts"
}

An unknown package returns 404 Not Found.

Read a page

GET /api/documentation/pages/{slug}

Path parameter	Type	Description
`slug`	string	A full page slug, e.g. `oi-laravel-ts/usage/data-objects`. Slugs contain slashes.

bash

curl "https://dev.olacombe.com/api/documentation/pages/oi-laravel-ts/getting-started"

json

{
    "data": {
        "slug": "oi-laravel-ts/getting-started",
        "title": "Introduction",
        "frontmatter": {
            "title": "Introduction",
            "description": "Discover OI Laravel TypeScript and what it can do for your project",
            "section": "getting-started",
            "order": 1
        },
        "markdown": "# OI Laravel TypeScript\n\nOI Laravel TypeScript automatically...",
        "tableOfContents": [
            { "level": 1, "title": "OI Laravel TypeScript", "slug": "oi-laravel-typescript" },
            { "level": 2, "title": "Why use this package?", "slug": "why-use-this-package" }
        ]
    }
}

An unknown slug returns 404 Not Found.

Errors

The API uses conventional HTTP status codes and a consistent JSON error body.

Status	When
`404 Not Found`	Unknown package slug or page slug.
`422 Unprocessable Entity`	Invalid query parameters (e.g. `q` shorter than 2 characters).
`429 Too Many Requests`	Rate limit exceeded (60 requests/minute).

A validation error (422) lists the offending fields under errors:

json

{
    "message": "The search query must be at least 2 characters long.",
    "errors": {
        "q": [
            "The search query must be at least 2 characters long."
        ]
    }
}

Other MCP clients

Generic configuration for any MCP-compatible tool

Conventions & Workflow

The shared, in-house standard behind every OI Laravel package — the pattern you learn once and recognise everywhere