> For the complete documentation index, see [llms.txt](https://whitepaper.litho.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whitepaper.litho.ai/docs/api-reference/rest-api.md).

# REST API Reference

> The machine-readable contract lives in [`openapi.yaml`](https://github.com/KaJLabs/lithosphere/blob/main/docs/api-reference/openapi.yaml). A CI drift gate (`openapi-sync-check`) fails any PR that adds, renames, or removes a route in `Makalu/api/src/{routes,litho}.ts` without a matching update there. Use the YAML when generating clients or running Postman/Insomnia against the API; treat this page as the prose tour.

## Overview

The Lithosphere REST API provides HTTP endpoints for interacting with the Lithosphere network. The API returns JSON responses and follows standard REST conventions.

## Base URL

The base URL is configurable via the `LITHO_RPC_URL` environment variable.

```
LITHO_RPC_URL=https://your-node-url.example.com
```

## Authentication

Authentication details are to be determined. This section will be updated once the authentication mechanism is finalized.

## Endpoints

### GET /health

Health check endpoint. Returns the current status of the node.

**Request:**

```bash
curl -X GET ${LITHO_RPC_URL}/health
```

**Response (200 OK):**

```json
{
  "status": "healthy",
  "timestamp": "2026-02-14T00:00:00.000Z"
}
```

### GET /api/litho

Returns chain information for the Lithosphere network.

**Request:**

```bash
curl -X GET ${LITHO_RPC_URL}/api/litho
```

**Response (200 OK):**

```json
{
  "chainId": 61,
  "network": "lithosphere",
  "version": "1.0.0"
}
```

## Response Format

All responses are returned in JSON format with appropriate `Content-Type: application/json` headers.

## Status Codes

| Code | Description                                                              |
| ---- | ------------------------------------------------------------------------ |
| 200  | OK -- The request was successful.                                        |
| 400  | Bad Request -- The request was malformed or missing required parameters. |
| 401  | Unauthorized -- Authentication failed or was not provided.               |
| 500  | Internal Server Error -- An unexpected error occurred on the server.     |

## Rate Limiting

Rate limiting details are to be determined. This section will be updated once rate limiting policies are implemented.

## Further Reading

Full API documentation is coming soon. Check back for comprehensive endpoint references, request/response schemas, and integration guides.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://whitepaper.litho.ai/docs/api-reference/rest-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.