TotalApp Docs
Ctrl K
Home
EN | TR
Go to App

API Playground

Test TotalApp's internal API endpoints interactively.

Overview

The API Playground is an interactive HTTP request builder for TotalApp's internal /api/* endpoints. It lets you send requests, inspect responses, and save frequently-used calls — all without leaving the browser. This is useful for debugging integration issues, testing AI endpoints with different prompts, or verifying that a data write succeeded.

Request Builder

The request builder has three controls:

  • Method selector — choose GET or POST. GET requests fetch data; POST requests create or update data.
  • Endpoint dropdown — select from the list of known /api/* endpoints. You can also type a custom path directly.
  • Request body editor — for POST requests, edit the JSON body. The editor validates JSON syntax before sending and highlights errors inline.

Click Send to dispatch the request. The playground uses the same origin as the TotalApp frontend, so no authentication headers are needed for internal endpoints.

Response Viewer

After sending a request, the response panel on the right shows:

  • HTTP status code with colour coding (green for 2xx, yellow for 3xx, red for 4xx/5xx)
  • Response time in milliseconds
  • Formatted JSON body with syntax highlighting and collapsible nested objects
  • Copy button to copy the raw response JSON to your clipboard

Saved Requests

Click the Save icon next to any request to bookmark it. Saved requests appear in the left panel under "Saved". Click a saved request to load its method, endpoint, and body back into the builder. This is useful for frequently-used queries like fetching a specific project or testing a Claude prompt with a fixed message.

Name Your Saved Requests

When saving a request, give it a descriptive name like "Fetch employees" or "Test Claude with marketing prompt". Generic names like "POST /api/claude" become confusing when you have multiple similar requests saved.

API Reference

MethodEndpointDescription
GET/api/data/employeesFetch all employee records
POST/api/data/employeesOverwrite the employees store with a new JSON payload
GET/api/data/projects-indexFetch the project index (all project metadata)
POST/api/claudeSend a prompt to Claude. Body: { "prompt": "...", "apiMode": "api" }
POST/api/storyteller/scriptGenerate a story script. Body: { "prompt": "...", "apiMode": "cohere" }
GET/api/data/financial-accountsFetch all financial account records (chart of accounts)
GET/api/data/ecommerce-reportsFetch all saved ecommerce AI reports
POST/api/shopify/assistantQuery the Shopify AI assistant. Body: { "messages": [...], "shopifyToken": "..." }

AI Assistant

Open the built-in AI Assistant from the tab on the right edge of the screen to get help interpreting a response or debugging a failed request. It has context on your current request (method, URL, headers, body) and the most recent response (status, response headers, body, timing, size) or error, so you can ask things like:

  • "Explain this response"
  • "What headers am I missing for this request?"
  • "Give me the equivalent curl command for this request"
  • "Help me fix the error in this request"

The assistant only reasons about the request/response you've actually sent — it never invents headers, status codes, or body content that weren't shown in the playground.

Frequently Asked Questions

Do requests sent from the Playground require authentication?
No manual token setup is needed for internal endpoints. Because the Playground runs on the same origin as the TotalApp frontend, your existing session/JWT is used automatically for any /api/data/* or tenant-scoped call, just as it would be from the main app. If you test an endpoint that expects an explicit Authorization: Bearer header (rare, mostly for admin-only routes), you can add it manually in the request body editor's headers section.
Why does my POST request fail with a JSON syntax error before it even sends?
The request body editor validates JSON syntax client-side and blocks sending until the body parses correctly — this saves a round trip for an error the server would reject anyway. Common causes are trailing commas, unquoted keys, or missing closing braces. The inline error highlight points to the exact line and character where parsing failed.
Are saved requests shared across my team or stored only on my machine?
Saved requests are tied to your own session in the Playground and are not automatically shared with teammates. If you want a colleague to reuse a specific call, the simplest approach is to share the endpoint, method, and JSON body directly (e.g. via chat or a note) so they can recreate it, since there is currently no team-wide saved-request library.
Can I use the Playground to test AI endpoints like /api/claude or /api/storyteller/script?
Yes — both are listed in the API Reference table above and behave like any other endpoint. Set the method to POST, select the endpoint from the dropdown (or type it manually), and provide a body such as { "prompt": "...", "apiMode": "api" }. The response viewer shows the generated text along with the HTTP status and response time, which is useful for comparing output across different apiMode values (e.g. "api" vs "cohere").