Developer Documentation

Authentication

All API requests require authentication via an API key. Include your key in the X-API-Key header:

X-API-Key: pk_live_your_api_key_here

Getting an API Key

1. Log in to PartWork Studio
2. Open Settings (gear icon)
3. Click "Manage" next to Developer API
4. Click "Create Key" and save your key securely

Permissions

API keys can be scoped with specific permissions:

Quick Start

Generate a CAD model with a single API call:

curl -X POST https://api.partwork.ai/v1/generate \
  -H "X-API-Key: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a 2 inch cube with rounded edges",
    "conversation_id": null
  }'

Response:

{
  "job_id": "job_abc123xyz",
  "status": "pending",
  "conversation_id": "conv_def456"
}

Poll for completion:

curl https://api.partwork.ai/v1/job/job_abc123xyz \
  -H "X-API-Key: pk_live_your_api_key"

When complete:

{
  "job_id": "job_abc123xyz",
  "status": "completed",
  "result": {
    "model_url": "https://...",
    "thumbnail_url": "https://...",
    "part_id": "part_789"
  }
}

Endpoints

Base URL: https://api.partwork.ai/v1

{
  "job_id": "job_abc123xyz",
  "status": "pending",
  "conversation_id": "conv_def456"
}

{
  "job_id": "job_abc123xyz",
  "status": "pending",
  "progress": 45
}

{
  "job_id": "job_abc123xyz",
  "status": "completed",
  "result": {
    "model_url": "https://...",
    "thumbnail_url": "https://...",
    "part_id": "part_789"
  }
}

{
  "job_id": "job_abc123xyz",
  "status": "failed",
  "error": "Could not generate model from prompt"
}

{
  "download_url": "https://...",
  "expires_at": "2025-01-15T12:00:00Z"
}

{
  "upload_url": "https://s3.amazonaws.com/...",
  "upload_id": "upload_xyz789",
  "expires_at": "2025-01-15T12:00:00Z"
}

{
  "job_id": "job_process123",
  "status": "pending"
}

{
  "conversations": [
    {
      "id": "conv_abc123",
      "name": "Mounting Bracket",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T14:22:00Z"
    }
  ],
  "next_cursor": "eyJsYXN0..."
}

{
  "id": "conv_abc123",
  "name": "Mounting Bracket",
  "parts": [
    {
      "id": "part_xyz789",
      "name": "Base Plate",
      "model_url": "https://...",
      "thumbnail_url": "https://..."
    }
  ],
  "created_at": "2025-01-15T10:30:00Z"
}

{
  "download_url": "https://s3.amazonaws.com/...",
  "expires_in": 3600
}

Rate Limits

API requests are rate limited based on your tier. Limits reset at the start of each period.

Rate Limit Headers

Every response includes rate limit information:

Errors

The API uses standard HTTP status codes and returns error details in the response body.

Error Response Format

{
  "error": "Invalid API key",
  "code": "invalid_api_key",
  "details": null
}

Common Error Codes

Code Examples

Python

import requests
import time

API_KEY = "pk_live_your_api_key"
BASE_URL = "https://api.partwork.ai/v1"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# Generate a part
response = requests.post(
    f"{BASE_URL}/generate",
    headers=headers,
    json={"prompt": "Create a 50mm diameter gear with 20 teeth"}
)
job = response.json()
print(f"Job started: {job['job_id']}")

# Poll for completion
while True:
    status = requests.get(
        f"{BASE_URL}/job/{job['job_id']}",
        headers=headers
    ).json()

    if status["status"] == "completed":
        print(f"Model URL: {status['result']['model_url']}")
        break
    elif status["status"] == "failed":
        print(f"Error: {status['error']}")
        break

    time.sleep(2)

# Download STEP file (if step_key is in result)
if "step_key" in status["result"]:
    download = requests.post(
        f"{BASE_URL}/download",
        headers=headers,
        json={"s3_key": status["result"]["step_key"]}
    ).json()
    print(f"STEP download: {download['download_url']}")

# Or export to a different format
export = requests.post(
    f"{BASE_URL}/export",
    headers=headers,
    json={
        "part_id": status["result"]["part_id"],
        "format": "stl"
    }
).json()
print(f"STL download: {export['download_url']}")

Node.js

const API_KEY = 'pk_live_your_api_key';
const BASE_URL = 'https://api.partwork.ai/v1';

const headers = {
  'X-API-Key': API_KEY,
  'Content-Type': 'application/json'
};

async function generatePart(prompt) {
  // Start generation
  const response = await fetch(`${BASE_URL}/generate`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ prompt })
  });
  const job = await response.json();
  console.log(`Job started: ${job.job_id}`);

  // Poll for completion
  while (true) {
    const statusRes = await fetch(`${BASE_URL}/job/${job.job_id}`, { headers });
    const status = await statusRes.json();

    if (status.status === 'completed') {
      return status.result;
    } else if (status.status === 'failed') {
      throw new Error(status.error);
    }

    await new Promise(r => setTimeout(r, 2000));
  }
}

// Usage
generatePart('Create a 2 inch cube with rounded edges')
  .then(result => console.log('Model URL:', result.model_url))
  .catch(err => console.error('Error:', err));

cURL

# Generate a part
curl -X POST https://api.partwork.ai/v1/generate \
  -H "X-API-Key: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Create a mounting bracket with 4 holes"}'

# Check job status
curl https://api.partwork.ai/v1/job/job_abc123 \
  -H "X-API-Key: pk_live_your_api_key"

# Download a STEP file (using s3_key from job result)
curl -X POST https://api.partwork.ai/v1/download \
  -H "X-API-Key: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"s3_key": "parts/abc123/model.step"}'

# Export to STL
curl -X POST https://api.partwork.ai/v1/export \
  -H "X-API-Key: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"part_id": "part_xyz789", "format": "stl"}'

# List conversations
curl https://api.partwork.ai/v1/conversations \
  -H "X-API-Key: pk_live_your_api_key"