Skip to content
Muse4AI
ENVI

Type at least one word. Vietnamese works with or without accents.

    Chapter · Connect AI agents

    REST API reference

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

    Updated Markdown for AI

    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. 1Check 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. 2Read 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. 3Choose 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. 4Use 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. 5Follow the existing job

      Poll the returned job ID. Never resubmit running or needs_review work. Follow the MCP retry rules, 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.