Z
Zynocode
Developer Portal
v2 REST Interface

REST API Reference

Programmatically query the tool catalog, inspect schemas, and execute computational tools on our backend infrastructure.

Server-Side Execution Notice

Unlike our interactive web browser tools which execute client-side using WebAssembly and HTML5 Canvas with zero server uploads, the Public REST API executes tool requests directly on Zynocode Labs backend servers. Input payloads transmitted to /api/v2/tools/:slug/execute are sent over encrypted TLS 1.3 to our application servers for processing.

API Overview & Specifications

Base URL

https://labs.zynocode.com

Transport & Encoding

HTTPS (TLS 1.3), JSON, UTF-8

Authentication Header

x-api-key: zk_live_...

Default Rate Limit

60 requests / minute (per key)

Authentication

Public catalog endpoints (GET /api/v2/tools and GET /api/v2/tools/:slug) are unauthenticated and openly accessible. Execution endpoints require an active API key with the tools:execute scope.

Send your key in either the x-api-key header or as a Bearer token in the Authorization header:

# Header Option 1: Dedicated Header
x-api-key: zk_live_your_api_key_here
# Header Option 2: Bearer Authorization
Authorization: Bearer zk_live_your_api_key_here

Plan Requirement Note:

API key execution requires an account plan with the apiAccess feature entitlement. If an API key associated with a free account attempts tool execution, the API returns HTTP 403 Forbidden with code FORBIDDEN.

Rate Limiting

Tool execution requests are tracked by PostgreSQL rate limiters. Standard API keys are limited to 60 requests per 60-second window. Every authenticated execution response includes diagnostic rate limit headers:

HeaderDescription
X-RateLimit-LimitMaximum permitted requests within the sliding window (e.g. 60).
X-RateLimit-RemainingRemaining available requests in the current window.
X-RateLimit-ResetUnix epoch timestamp (seconds) when the window resets.
Retry-AfterReturned on HTTP 429; seconds to pause before retrying.

Idempotency & Replay Protection

To prevent duplicate execution and unintended credit consumption on network retries, you can provide an Idempotency-Key header or specify an explicit executionId in your request payload:

# Header:
Idempotency-Key: req_unique_client_hash_9823

If a completed execution already exists with the same ID, user, and input hash, the API returns the original output with "isReplayed": true without recalculating or deducting additional credits.

Endpoints

GET/api/v2/toolsPublic · Unauthenticated

Returns the list of active tools in the catalog, with optional filtering by category or keyword search.

Query Parameters
  • category (string, optional): Filter by category (e.g. developer, finance, utility, seo, writing).
  • search (string, optional): Case-insensitive match on tool name, slug, or description.
  • activeOnly (boolean, optional): Default true. Pass false to include all statuses.
Example Request
curl -s "https://labs.zynocode.com/api/v2/tools?category=developer"
Example Response (HTTP 200)
{
  "success": true,
  "tools": [
    {
      "id": "314e17cc-5fd8-40b4-80ab-2e1172ac2039",
      "slug": "json-formatter",
      "name": "JSON Formatter",
      "description": "Format, validate, and minify JSON with syntax highlighting.",
      "category": "developer",
      "status": "active",
      "creditCost": 0,
      "isNew": true,
      "isPopular": false
    }
  ],
  "count": 18
}
GET/api/v2/tools/:slugPublic · Unauthenticated

Returns detailed metadata and status for a single tool identified by its canonical slug.

Example Request
curl -s "https://labs.zynocode.com/api/v2/tools/emi-calculator"
Example Response (HTTP 200)
{
  "success": true,
  "tool": {
    "id": "c81a6315-9b22-4ca3-a609-a826c03a4ca2",
    "slug": "emi-calculator",
    "name": "EMI Calculator",
    "description": "Calculate your loan EMI easily with detailed breakdown.",
    "category": "finance",
    "status": "active",
    "creditCost": 0
  }
}
POST/api/v2/tools/:slug/executeAuthentication Required

Executes a tool on our backend with the supplied parameters. Maximum allowed JSON request payload is 512 KB.

Request Headers
  • Content-Type: application/json
  • x-api-key: zk_live_your_api_key_here
  • Idempotency-Key (optional): Unique string to guarantee at-most-once execution on network retry.
Example Request (Word Counter)
curl -s -X POST "https://labs.zynocode.com/api/v2/tools/word-counter/execute" \ -H "Content-Type: application/json" \ -H "x-api-key: zk_live_your_api_key_here" \ -d '{"params":{"text":"Hello world from Zynocode API."}}'
Example Response (HTTP 200)
{
  "success": true,
  "executionId": "exec_1c2cb7e8-0af6-45c1-bec7-539fc00069f4",
  "status": "completed",
  "durationMs": 1,
  "creditsConsumed": 0,
  "isReplayed": false,
  "result": {
    "words": 5,
    "characters": 30,
    "sentences": 1,
    "paragraphs": 1,
    "readingTimeMinutes": 1
  },
  "outputSummary": "5 words, 1 sentences, ~1 min read"
}
GET/api/v2/executions/:executionIdAuthentication Required

Fetches the stored audit record, metadata, and status of an execution by its execution ID.

Example Request
curl -s "https://labs.zynocode.com/api/v2/executions/exec_1c2cb7e8-0af6-45c1-bec7-539fc00069f4" \ -H "x-api-key: zk_live_your_api_key_here"
Example Response (HTTP 200)
{
  "success": true,
  "execution": {
    "id": "53c0184b-273d-4efb-b21f-f85e3debafc3",
    "executionId": "exec_1c2cb7e8-0af6-45c1-bec7-539fc00069f4",
    "toolSlug": "word-counter",
    "status": "completed",
    "durationMs": 1,
    "creditsConsumed": 0,
    "inputPayload": {
      "text": "Hello world from Zynocode API."
    },
    "outputReference": "5 words, 1 sentences, ~1 min read"
  }
}

Error Codes & Diagnostics

Errors return structured JSON responses with a human-readable error message and machine-readable code:

HTTP StatusCodeDescription
400 Bad RequestVALIDATION_ERRORMissing parameters, invalid slug, or payload exceeds 512 KB.
401 UnauthorizedUNAUTHORIZEDMissing, revoked, expired, or invalid API key format.
403 ForbiddenFORBIDDENAccount lacks apiAccess entitlement or tool is deprecated.
404 Not FoundNOT_FOUNDTool slug or execution record was not found in the database.
429 Too Many RequestsRATE_LIMIT_EXCEEDEDRequest rate exceeds 60 req/min. Check Retry-After header.
500 Server ErrorINTERNAL_ERRORUnhandled server or execution engine exception.