Skip to main content

API Reference

Welcome to the Kloddy API. Our REST API is designed to be predictable, resource-oriented, and uses standard HTTP response codes and authentication.

Base URLs​

The Kloddy API is served over HTTPS to ensure data privacy and security.

EnvironmentBase URL
Productionhttps://api.kloddy.com
Developmenthttp://localhost:3001

Authentication​

Kloddy uses JSON Web Tokens (JWT) for authentication. All API requests must include your token in the Authorization HTTP header.

1. Get an Access Token​

Exchange your applicationId and secretKey for a JWT.

POST/api/login

Body Parameters

  • applicationId (string, required)
  • secretKey (string, required)

2. CLI Polling​

Used by the Kloddy CLI for long-running OAuth flows.

GET/api/poll

Query Parameters

  • code (string, required): The session hash.

Core Endpoints​

User & Identity​

GET/api/whoiam

Returns the identity profile for the current authenticated session.

Organizations​

GET/api/organizations

Lists all organizations the current user has access to.

Prompts & Execution​

List Prompts​

GET/api/prompts

Query Parameters

  • page (number)
  • pageSize (number)
  • name (string): Filter by name.
  • org_id (uuid): Filter by organization.

Execute Prompt (Play)​

Run a prompt version through a model with specific variables.

POST/api/prompt/[name]

Body Parameters

  • variables (object): Key-value pairs for prompt injection.
  • model (string): The AI model to use (e.g., gpt-4o).
  • version (string): The specific prompt version.
  • resolve (boolean): Whether to resolve @mentions.
Example Request
curl -X POST https://api.kloddy.com/api/prompt/hello-world \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"variables": {"user": "Alice"}}'

Evaluations​

Compare multiple models or versions using a judge-based evaluation.

POST/api/evaluate

Request Body

{
  "name": "prompt-name",
  "models": ["gpt-4o", "claude-3-5-sonnet"],
  "judge": "gpt-4o",
  "version": ["v1", "v2"],
  "variables": { "input": "test data" }
}