# REST API reference

Use the local REST API with a Bearer key, inspect its OpenAPI document, and follow jobs without submitting duplicates.

Source: https://muse4ai.lovable.app/docs/rest-api · Updated 2026-11-02

## Before you start

- Enable API for agents and create a key with the required scope.
- The default base URL is http://127.0.0.1:47821/v1. Use the app’s current address if its port changed.

## 1. Check server access

Open Settings › API & agent. Keep access local unless another machine needs it. Send your key in Authorization: Bearer, never in the URL.

## 2. Read status

Run this in a terminal, replacing the placeholder with your own key. On Windows, curl.exe avoids a PowerShell command alias.

```powershell
curl.exe "http://127.0.0.1:47821/v1/status" -H "Authorization: Bearer msk_YOUR_KEY"
```

## 3. Choose an endpoint

Paths below are relative to the base URL:
- GET /health — liveness; no key required.
- GET /openapi.json — API schema; no key required.
- GET /status — readiness and capabilities.
- GET or POST /jobs — list or submit jobs.
- GET /jobs/{id} — job details and results.
- POST /jobs/{id}/cancel — request cancellation.
- POST /references — upload reference bytes.
- GET or HEAD /assets/{id}/content — fetch an output with a key or valid signature.
- GET /conversations/{id} — read a conversation.
- POST /assets/{id}/extend or /conversations/{id}/extend — start an extension.
- GET /extend-chains/{id} — read an extension chain.
- POST /extend-chains/{id}/cancel — cancel a chain.

## 4. Use the live schema

The server exposes its OpenAPI document at http://127.0.0.1:47821/v1/openapi.json without a key. Read it for request fields and responses. Give each new submission a unique request_id; preserve it when retrying the same interrupted request.

## 5. Follow the existing job

Poll the returned job ID. Never resubmit running or needs_review work. Follow the [MCP retry rules](https://muse4ai.lovable.app/docs/mcp-tools), which apply to the same underlying jobs.

## Check it worked

An authenticated status request succeeds and your client can read the server’s schema.

## If it doesn't work

### Why does health work but status fails?

Health is public. Status requires an active key in the Bearer header.

### Why do I get not found?

Check that the base includes /v1, and compare the route and method with the OpenAPI document.