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:

POST /v1/keys/{api_key_id}/rotate-secret
Authorization: Bearer mk_pub_...

Returns a new signing_secret (shown once) and signing_secret_rotated_at timestamp. Webhooks will immediately use the new secret for signing.

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