---
title: REST API
description: The Atlas by Friendlym REST API. Every MCP tool as a POST endpoint under /api/v1, an OpenAPI 3.1 description, JSON errors, rate limit headers and the versioning policy.
canonical: https://tilqui-atlas.pages.dev/docs/api/?lang=en
lang: en
last_updated: 2026-10-08
alternate_html: https://tilqui-atlas.pages.dev/docs/api/?lang=en
---

# REST API

Every tool of the MCP server is also a REST endpoint with the same name, input and result:

```sh
curl -s https://tilqui-atlas.pages.dev/api/v1/tools/list_projects \
  -H "authorization: Bearer $ATLAS_TOKEN" -H 'content-type: application/json' -d '{}'
```

- Base URL: `https://tilqui-atlas.pages.dev/api/v1`
- Description: [OpenAPI 3.1](https://tilqui-atlas.pages.dev/openapi.json), also listed in the [API catalog](https://tilqui-atlas.pages.dev/.well-known/api-catalog) (RFC 9727)
- Auth: OAuth 2.1 bearer tokens (see [authentication](https://tilqui-atlas.pages.dev/docs/auth/?lang=en)) or a pairing token
- Every operation has an `operationId`, typed request and response schemas, and hints (read only, idempotent)

`GET /api/v1/me` tells you who a token acts for and which scopes it has.

## Results and errors

A tool answers `200` with `{"ok": true, "data": …}`. Errors are JSON with a stable code and a sentence that says what to do:

```json
{ "ok": false, "error": { "code": "scope_missing", "message": "This token has no ask scope. …" } }
```

| Status | Code | What to do |
|---|---|---|
| 400 | `invalid_input` | Fix the input; the message names the field |
| 401 | `unauthorized` | Sign in again; `WWW-Authenticate` points at the metadata |
| 403 | `scope_missing` | Ask the person to approve the scope |
| 404 | `not_found` | Check the tool name or the id |
| 429 | `rate_limited` | Wait `Retry-After` seconds |
| 503 | `unavailable` | Try again shortly |

## Rate limits

Each agent has an hourly budget of tool calls shared by MCP and REST (300 by default), and `ask_atlas` has a daily limit. Responses carry the IETF rate limit fields:

```text
RateLimit-Policy: "hour";q=300;w=3600
RateLimit: "hour";r=297;t=3600
```

A `429` carries `Retry-After`.

## Versioning and deprecation

The path carries the major version: `/api/v1`. Additive changes (a new tool, a new optional field, a new result field) keep the version. A breaking change gets `/api/v2`, and `/api/v1` keeps working for at least 90 days, with `Deprecation` and `Sunset` headers and a note on this page. The MCP tools follow the same rule.