Skip to main content

API Overview

Zamski provides a comprehensive API that allows you to integrate our platform with your existing tools and workflows. This guide provides an overview of the API and how to get started.

API Basics​

Authentication​

All API requests require authentication using an API key:

curl -X GET "https://api.zamski.com/v1/projects" \
     -H "Authorization: Bearer YOUR_API_KEY"

To get an API key:

  1. Navigate to Settings > API Keys in the Zamski dashboard
  2. Click Create API Key
  3. Name your key and select the appropriate permission scope
  4. Store the key securely — it will only be shown once

Base URL​

All API endpoints use the following base URL:

https://api.zamski.com/v1

Response Format​

All responses are returned in JSON format:

{
  "data": {
    // Response data here
  },
  "meta": {
    // Metadata about the response
    "requestId": "req_123abc",
    "timestamp": "2025-05-04T12:30:45Z"
  }
}

Error Handling​

Errors return appropriate HTTP status codes and detailed error messages:

{
  "error": {
    "code": "invalid_request",
    "message": "The request was invalid",
    "details": "Project ID is required",
    "requestId": "req_123abc"
  }
}

API Resources​

Projects​

Manage projects in your Zamski organization:

  • GET /projects - List all projects
  • GET /projects/{id} - Get details for a specific project
  • POST /projects - Create a new project
  • PUT /projects/{id} - Update an existing project
  • DELETE /projects/{id} - Delete a project

Teams​

Manage teams within your organization:

  • GET /teams - List all teams
  • GET /teams/{id} - Get details for a specific team
  • POST /teams - Create a new team
  • PUT /teams/{id} - Update a team
  • DELETE /teams/{id} - Delete a team

Users​

Manage users within your organization:

  • GET /users - List all users
  • GET /users/{id} - Get details for a specific user
  • POST /users/invite - Invite a new user
  • PUT /users/{id} - Update a user's settings
  • DELETE /users/{id} - Remove a user

PRD Analysis​

Interact with the PRD Analysis feature:

  • POST /prd-analysis - Upload and analyze a PRD
  • GET /prd-analysis/{id} - Get analysis results
  • GET /prd-analysis/{id}/annotations - Get document annotations
  • GET /prd-analysis/{id}/technical - Get technical analysis

Sprint Simulation​

Work with the Sprint Simulator:

  • POST /simulations - Create a new simulation
  • GET /simulations/{id} - Get simulation results
  • POST /simulations/{id}/run - Run or re-run a simulation
  • GET /simulations/{id}/scenarios - Get simulation scenarios

Metrics​

Access metrics and analytics data:

  • GET /metrics/sprint/{id} - Get sprint metrics
  • GET /metrics/team/{id} - Get team performance metrics
  • GET /metrics/project/{id} - Get project metrics
  • GET /metrics/custom - Get custom metrics

Webhooks​

Zamski supports webhooks to notify your systems when events occur:

Setting Up Webhooks​

  1. Navigate to Settings > Webhooks in the Zamski dashboard
  2. Click Add Webhook
  3. Enter the webhook URL
  4. Select the events you want to subscribe to
  5. Click Create Webhook

Available Events​

  • project.created - A new project is created
  • prd.analyzed - A PRD analysis is complete
  • simulation.completed - A sprint simulation is complete
  • sprint.started - A sprint has started
  • sprint.completed - A sprint has completed

Webhook Format​

Webhook payloads are sent as JSON:

{
  "event": "prd.analyzed",
  "timestamp": "2025-05-04T12:30:45Z",
  "data": {
    "id": "prd_123abc",
    "name": "User Authentication PRD",
    "status": "completed",
    "url": "https://app.zamski.com/prd/prd_123abc"
  }
}

Rate Limits​

API requests are subject to rate limiting:

  • Free tier: 100 requests per minute
  • Pro tier: 500 requests per minute
  • Enterprise tier: 2000 requests per minute

The rate limit headers are included in all responses:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 498
X-RateLimit-Reset: 1620123600

SDKs and Client Libraries​

Zamski offers client libraries for popular languages:

JavaScript Example​

import { ZamskiClient } from '@zamski/client';

const client = new ZamskiClient('YOUR_API_KEY');

async function listProjects() {
  const projects = await client.projects.list();
  console.log(projects);
}

listProjects();

Python Example​

from zamski import ZamskiClient

client = ZamskiClient('YOUR_API_KEY')

projects = client.projects.list()
print(projects)

Best Practices​

  • Store API keys securely: Never expose your API keys in client-side code
  • Handle rate limits gracefully: Implement backoff strategies for rate limits
  • Validate input: Always validate input before making API calls
  • Use webhooks for events: Use webhooks rather than polling for changes
  • Monitor usage: Keep track of your API usage to avoid hitting limits

Next Steps​