Authentication

All Makistry API requests are authenticated with a Bearer token.

API Keys

Format: mk_pub_<32 hex chars>

Header:

Authorization: Bearer mk_pub_YOUR_KEY

Security: Never put mk_pub_ keys in client-side code, browser JavaScript, or public repositories. Anyone who has the key can make API requests billed to your account. Store keys in environment variables or a secrets manager. If a key is ever exposed, revoke it from the dashboard immediately and issue a new one.

Creating a Key

From the dashboard, create a new API key. On creation you receive:

Store both api_key and signing_secret securely at creation time.

Rotating the Signing Secret

If your signing secret is ever compromised, rotate it without affecting the API key from the dashboard. The rotation takes effect immediately — webhooks will use the new secret for all deliveries from that point on. The old secret stops working instantly, so update your webhook handler before rotating if you need zero-downtime rotation.

Revoking a Key

From the dashboard, revoke a key to permanently invalidate it. Requests using a revoked key return 401 invalid_api_key.

Idempotency

Add an Idempotency-Key header to POST requests to safely retry network failures without creating duplicate jobs or double-charging:

Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890

• Use a UUID v4 generated fresh for each distinct request
• If the server receives the same key again, it returns the original job_id — even if the request body differs
• Edge case: the same idempotency key always returns the original job, regardless of what body you send. If you want a new job, use a new UUID.
• No additional charge is incurred on idempotent replays

Recommended pattern for retrying network failures:

import uuid, httpx, time

def submit_with_retry(prompt: str, max_attempts: int = 3) -> str:
    idem_key = str(uuid.uuid4())  # one key per logical request
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Idempotency-Key": idem_key,
    }
    for attempt in range(max_attempts):
        try:
            resp = httpx.post(f"{BASE}/text-to-cad", headers=headers,
                              json={"prompt": prompt, "output_format": "STEP"})
            resp.raise_for_status()
            return resp.json()["job_id"]
        except httpx.NetworkError:
            if attempt == max_attempts - 1:
                raise
            time.sleep(2 ** attempt)

Making an Authenticated Request

curl

curl https://api.makistry.ai/v1/jobs \
  -H "Authorization: Bearer mk_pub_YOUR_KEY"

Python

import httpx

client = httpx.Client(headers={"Authorization": "Bearer mk_pub_YOUR_KEY"})
resp = client.get("https://api.makistry.ai/v1/jobs")
resp.raise_for_status()
print(resp.json())

Node.js

const resp = await fetch("https://api.makistry.ai/v1/jobs", {
  headers: { "Authorization": "Bearer mk_pub_YOUR_KEY" },
});
const data = await resp.json();

Error Responses