ZeroPrompt API Reference

Every endpoint in this document is relative to the API base URL.

GET {{base_url}}/health
Content-Type: application/json

Authorization: Bearer <clerk_jwt_or_zp_api_key>
X-API-Key: zp_your_api_key_here

# 1) Health check (no auth required)
curl -sS "${BASE_URL}/health"

# 2) Create API key (requires Clerk JWT + Pro/Team plan)
curl -sS -X POST "${BASE_URL}/api-keys" \
  -H "Authorization: Bearer ${CLERK_JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI Integration",
    "expirationDays": 30,
    "permissions": {
      "read": true,
      "write": true,
      "create": true,
      "delete": false
    }
  }'

# 3) List prompts using API key
curl -sS "${BASE_URL}/prompts?limit=20&offset=0" \
  -H "X-API-Key: ${ZP_API_KEY}"

# 4) Create prompt using API key
curl -sS -X POST "${BASE_URL}/prompts" \
  -H "X-API-Key: ${ZP_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Customer Support Assistant",
    "description": "Structured support assistant prompt",
    "tags": ["support", "email"],
    "visibility": "PRIVATE",
    "lifecycle": "DRAFT",
    "sections": [
      {
        "id": "role-1",
        "type": "role",
        "title": "Role",
        "content": "You are a concise and helpful support assistant.",
        "order": 0
      },
      {
        "id": "task-1",
        "type": "task",
        "title": "Task",
        "content": "Draft a response to the customer using provided context.",
        "order": 1
      }
    ],
    "variables": [
      {
        "name": "customer_name",
        "label": "Customer Name",
        "type": "STRING",
        "required": true
      }
    ]
  }'

1. Create an environment variable named base_url (for example https://zeroprompt.knmlabs.org/api).
2. Add variables clerk_jwt and zp_api_key.
3. For API key requests, add a Header: X-API-Key: {{zp_api_key}}.
4. For JWT requests, use Authorization tab and select Bearer Token with value {{clerk_jwt}}.
5. Use URLs like {{base_url}}/prompts.

Postman Request Example
Method: POST
URL: {{base_url}}/contexts
Headers:
  Content-Type: application/json
  X-API-Key: {{zp_api_key}}
Body (raw JSON):
{
  "title": "Brand Voice",
  "description": "House style guidance",
  "content": "Use concise, technical language with actionable next steps.",
  "visibility": "PRIVATE",
  "lifecycle": "DRAFT",
  "isProOnly": false
}

1. Create an environment with base_url, clerk_jwt, and zp_api_key.
2. Set request URL to {{ base_url }}/packages.
3. For API key auth, add Header X-API-Key and value {{ zp_api_key }}.
4. For JWT auth, use Bearer token with {{ clerk_jwt }}.
5. Use JSON body mode for POST/PUT requests.

Insomnia Endpoint Examples
GET  {{ base_url }}/health
GET  {{ base_url }}/prompts
POST {{ base_url }}/packages
PUT  {{ base_url }}/prompts/REPLACE_PROMPT_ID
DELETE {{ base_url }}/contexts/REPLACE_CONTEXT_ID

API Key Management (JWT required)

Note: API key creation requires an eligible account (Pro/Team/Admin).

API Key-Compatible CRUD Endpoints

API keys are intentionally restricted to prompt, package (collection), context, and tag CRUD routes.

Public Endpoints (No auth)

Create API Key

{
  "name": "Automation Key",
  "expirationDays": 30,
  "permissions": {
    "read": true,
    "write": true,
    "create": true,
    "delete": false
  },
  "tagIds": [],
  "collectionIds": []
}

Create Collection (Package)

{
  "name": "Customer Success Library",
  "description": "Prompts and contexts for customer success workflows",
  "visibility": "PRIVATE",
  "icon": "folder",
  "promptIds": [],
  "contextIds": []
}

Create Context

{
  "title": "Incident Response Policy",
  "description": "Escalation and communication rules",
  "content": "P1 incidents must be acknowledged in 5 minutes...",
  "visibility": "PRIVATE",
  "lifecycle": "DRAFT",
  "isProOnly": false
}

• 401: Missing/invalid token or expired key.
• 403: Route/scope not allowed for this API key, or plan restriction.
• 404: Resource not found (or outside your ownership/scope).
• 429: Rate limit hit (standard routes: 120 req/min).

{
  "error": "API key missing required permission: write"
}

Tip: if an API key call returns 403 on a non-CRUD route, switch to Clerk JWT auth for that endpoint.