Playground

Docsalot can turn API docs into a working request builder directly inside your docs site. You can mix human-written guides with generated endpoint references, then let readers authenticate and test requests without leaving the page.

​

What to configure

Most projects start with a shared api block in layout.json.

{
  "api": {
    "baseUrl": "https://docsalot.dev/api/cli/v1",
    "auth": {
      "method": "bearer"
    },
    "playground": {
      "display": "interactive",
      "proxy": false
    },
    "examples": {
      "languages": ["curl", "javascript", "python"],
      "defaults": "required",
      "prefill": true
    }
  }
}

Use this block to set:

• the default API base URL
• the authentication method readers should use
• whether the playground is interactive, simplified, or hidden
• which example languages appear first

If you need the exact auth configuration options, continue to Authentication.

​

Two ways to build API docs

​

OpenAPI-backed pages

Use openapi: metadata when you already have a specification file and want Docsalot to render parameters, schemas, examples, and the request UI from it.

---
title: "List documentations"
openapi: "GET /documentations"
---

​

Manual API pages

Use api: metadata when you want full editorial control or you are prototyping an endpoint before the spec is finalized.

---
title: "Create documentation"
api: "POST /documentations"
---

​

Local testing

If you want the browser to send requests directly to a local backend during preview, temporarily point api.baseUrl to your local API and disable proxying if your setup expects direct browser requests.

{
  "api": {
    "baseUrl": "http://localhost:3000/api/cli/v1",
    "playground": {
      "proxy": false
    }
  }
}

Make sure your API allows the required CORS headers when requests come straight from the browser.

​

Browser editing demo

The Docsalot CLI API also supports a lightweight browser flow for editing one file at a time without pulling the entire docs bundle first.

​

Flow

1. GET /documentations/{documentationId}/manifest
2. POST /documentations/{documentationId}/docs/paths
3. POST /documentations/{documentationId}/docs/paths/push

​

Example

const API_BASE = "https://docsalot.dev/api/cli/v1";
const DOCUMENTATION_ID = "your-documentation-id";
const TOKEN = "your bearer token";
const TARGET_PATH = "quickstart.mdx";

async function api(path, init = {}) {
  const response = await fetch(`${API_BASE}${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      "Content-Type": "application/json",
      ...(init.headers || {}),
    },
  });

  if (!response.ok) {
    throw new Error(await response.text());
  }

  return response.json();
}

async function updateOneFile() {
  const manifest = await api(`/documentations/${DOCUMENTATION_ID}/manifest`);
  const target = manifest.files.find((file) => file.path === TARGET_PATH);

  if (!target) {
    throw new Error(`Path not found in manifest: ${TARGET_PATH}`);
  }

  const pulled = await api(`/documentations/${DOCUMENTATION_ID}/docs/paths`, {
    method: "POST",
    body: JSON.stringify({
      paths: [TARGET_PATH],
    }),
  });

  const file = pulled.files[0];
  const updatedContent = `${file.content}\n\nEdited from the browser.\n`;

  const pushed = await api(`/documentations/${DOCUMENTATION_ID}/docs/paths/push`, {
    method: "POST",
    body: JSON.stringify({
      files: [
        {
          path: file.path,
          title: file.title,
          content: updatedContent,
        },
      ],
      message: "Edit one file from browser demo",
    }),
  });

  return {
    manifest,
    pulled,
    pushed,
  };
}

This flow is useful when you want to:

• fetch metadata without downloading every file body
• pull only the file the user wants to edit
• push only the changed files back to Docsalot

​

Recommended flow

1. Add your OpenAPI or AsyncAPI files to the docs repo.
2. Configure shared API defaults in layout.json.
3. Add generated or manual API pages to navigation.
4. Test the flow locally before publishing.

Continue with OpenAPI setup for REST APIs or Create manual API pages when you want a hand-authored layout.