> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nylio.app/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Base URL, authentication, rate limits, and endpoint summary for the Nylio public REST API.

The public API powers the CLI and the hosted MCP transport.

## Base URL

```txt theme={null}
https://api.nylio.app/api/public/v1
```

## OpenAPI

* OpenAPI JSON: `https://api.nylio.app/api/public/v1/openapi.json`
* HTML docs: `https://api.nylio.app/api/public/v1/docs`
* Markdown guide JSON: `https://api.nylio.app/api/public/v1/markdown-guide`

The API reference section in this site is generated from the hosted OpenAPI document.

## Authentication

The public API supports two authentication methods. Each request must use exactly one. Sending both a bearer token and an API key in the same request returns `400 invalid_request`.

### OAuth bearer tokens

The public REST API expects bearer tokens for this audience:

```txt theme={null}
https://api.nylio.app/api/public/v1
```

Available scopes:

* `workspace:read`
* `document:read`
* `document:write`
* `search:read`

### API keys

For scripts and direct API usage, you can create API keys in the [developer settings](https://nylio.app/app/developer/api-keys).

Send the key in the `x-api-key` header:

```bash theme={null}
curl https://api.nylio.app/api/public/v1/workspaces \
  -H "x-api-key: nylio_YOUR_KEY"
```

When you create an API key, you choose which scopes it has. If a key lacks the scope required by an endpoint, the server returns `403 insufficient_scope`.

## Rate limits

All public API rate limits are enforced per IP address.

| Rule                | Path prefix             | Methods | Requests | Window |
| ------------------- | ----------------------- | ------- | -------- | ------ |
| `public-api-search` | `/api/public/v1/search` | `GET`   | 30       | 60 s   |
| `public-api-mcp`    | `/api/public/v1/mcp`    | all     | 60       | 60 s   |
| `public-api-read`   | `/api/public/v1`        | `GET`   | 120      | 60 s   |
| `oauth-discovery`   | `/.well-known/`         | `GET`   | 300      | 60 s   |

Responses include these headers:

| Header                  | Description                                           |
| ----------------------- | ----------------------------------------------------- |
| `x-ratelimit-limit`     | Maximum requests in the current window                |
| `x-ratelimit-remaining` | Requests remaining in the current window              |
| `x-ratelimit-reset`     | Unix timestamp in milliseconds when the window resets |
| `x-ratelimit-rule`      | Identifier of the matched rule                        |
| `retry-after`           | Present on `429` responses, in seconds                |

## Covered endpoints

| Endpoint                  | Scope            | Description                                  |
| ------------------------- | ---------------- | -------------------------------------------- |
| `GET /markdown-guide`     | --               | Returns the Nylio enhanced markdown guide    |
| `GET /workspaces`         | `workspace:read` | Lists accessible workspaces                  |
| `GET /workspaces/current` | `workspace:read` | Resolves the current workspace               |
| `GET /documents`          | `document:read`  | Lists documents in a workspace               |
| `GET /documents/{id}`     | `document:read`  | Reads one document with body markdown        |
| `POST /documents`         | `document:write` | Creates a personal document                  |
| `POST /documents/edit`    | `document:write` | Applies one string replacement               |
| `POST /documents/replace` | `document:write` | Replaces the full document body              |
| `POST /documents/export`  | `document:read`  | Exports a document as markdown, DOCX, or PDF |
| `GET /search`             | `search:read`    | Searches documents in a workspace            |

### Workspace targeting

Several endpoints accept optional query parameters to target a specific workspace:

| Parameter        | Description                  |
| ---------------- | ---------------------------- |
| `workspaceScope` | `personal` or `organization` |
| `workspaceSlug`  | Slug of the target workspace |

These parameters are supported on: `GET /workspaces/current`, `GET /documents`, `GET /documents/{id}`, `POST /documents/export`, and `GET /search`.

### Search query parameter

The `GET /search` endpoint expects the search term in a query parameter named `q`:

```bash theme={null}
curl "https://api.nylio.app/api/public/v1/search?q=project+plan" \
  -H "x-api-key: YOUR_API_KEY"
```

### Export options

`POST /documents/export` accepts an optional `fileName` field in the request body to control the output file name.

## Write semantics

* Read endpoints can access workspaces and documents available to the authenticated user.
* Create, edit, and replace endpoints are limited to personal documents owned by the authenticated user.
* Document write endpoints use [Nylio enhanced markdown](/format/nylio-markdown).
* Create, edit, and replace responses return compact document summaries. Call `GET /documents/{id}` to read the full body.
* Export returns standard markdown text or base64-encoded binary payloads for PDF and DOCX.

<Warning>
  Read the [Nylio markdown guide](/format/nylio-markdown) before constructing write payloads. Plain markdown is not accepted by write endpoints.
</Warning>

<Info>
  POST write endpoints (`/documents`, `/documents/edit`, `/documents/replace`) are not covered by the `public-api-read` rate limit rule. They still require authentication and scope checks but do not have a separate published rate limit at this time.
</Info>