Zynapse (ZkAGI) — API Documentation

Welcome to the Zynapse API. These endpoints let you generate privacy-preserving proofs for documents (ZK-style provenance), perform knowledgebase Q&A with proof attachment, and create media (images & videos). Admin endpoints are provided for user management and API key lifecycle.

Base URL: https://zynapse.zkagi.ai

---

How do I authenticate with the Zynapse API?

All Zynapse API endpoints require an API key passed via the X-API-Key header unless explicitly noted otherwise. Keep your keys secret, and use the admin endpoints to rotate or revoke them when needed.

• Header format: X-API-Key: <your_api_key>
• Supported content types:
  • File upload: multipart/form-data
  • JSON: application/json
  • Downloads: binary stream unless otherwise specified
• Rotate and revoke keys using the Admin endpoints described below

---

How do I ask questions with proof using the Zynapse API?

Send a POST request to /v1/ask with your question and a proof JSON file to perform Q&A over your document set with cryptographic proof attachment. The proof file must first be generated via the /v1/generate_proof endpoint.

• Endpoint: POST /v1/ask
• Headers: X-API-Key
• Content-Type: multipart/form-data
• Form fields:
  • query (string, required) — The user question.
  • proof_file (file, required) — Proof JSON generated by /v1/generate_proof.

cURL

curl -s -X POST "https://zynapse.zkagi.ai/v1/ask" \
  -H "X-API-Key: <YOUR_KEY>" \
  -F "query=What is this document about?" \
  -F "[email protected];filename=proof.json;type=application/json"

Tip: if proof.json is coming from stdin, you can pipe it: ... -F "proof_file=@-;filename=proof.json;type=application/json"

Node.js (fetch)

const form = new FormData();
form.append("query", "What is this document about?");
form.append("proof_file", new Blob([JSON.stringify(proofObj)], { type: "application/json" }), "proof.json");

const res = await fetch("https://zynapse.zkagi.ai/v1/ask", {
  method: "POST",
  headers: { "X-API-Key": process.env.ZYNAPSE_API_KEY },
  body: form
});
const data = await res.json();

Python

import requests
files = {
  'query': (None, 'What is this document about?'),
  'proof_file': ('proof.json', open('proof.json','rb'), 'application/json')
}
r = requests.post('https://zynapse.zkagi.ai/v1/ask', headers={'X-API-Key': 'YOUR_KEY'}, files=files)
print(r.json())

Response (example)

{
  "answer": "This document is a resume highlighting...",
  "references": [{"title": "vivek_resume.pdf", "page": 1}],
  "used_proof": true,
  "latency_ms": 842
}

---

How do I generate a proof for a file using Zynapse?

Upload a document to POST /v1/generate_proof to receive a proof artifact that you can later pass to /v1/ask for verified Q&A. The endpoint accepts PDF, image, and text files via multipart form data.

• Endpoint: POST /v1/generate_proof
• Headers: X-API-Key
• Content-Type: multipart/form-data
• Form fields:
  • file (file, required) — PDF/image/text you want to index/prove.

cURL

curl -s -X POST "https://zynapse.zkagi.ai/v1/generate_proof" \
  -H "X-API-Key: <YOUR_KEY>" \
  -F "file=@vivek_resume.pdf" \
  -o proof.json

Node.js (fetch)

const form = new FormData();
form.append("file", fs.createReadStream("vivek_resume.pdf"));
const res = await fetch("https://zynapse.zkagi.ai/v1/generate_proof", {
  method: "POST",
  headers: { "X-API-Key": process.env.ZYNAPSE_API_KEY },
  body: form
});
const proof = await res.json();

Python

import requests
r = requests.post(
  'https://zynapse.zkagi.ai/v1/generate_proof',
  headers={'X-API-Key': 'YOUR_KEY'},
  files={'file': open('vivek_resume.pdf','rb')}
)
open('proof.json','wb').write(r.content)

Response (example)

{
  "proof_version": "1.0",
  "doc_hash": "sha256:...",
  "created_at": "2025-10-11T10:20:00Z",
  "segments": [ { "page": 1, "hash": "..." } ]
}

---

How do I generate images with the Zynapse API?

Send a JSON POST request to /v1/generate/image with a text prompt and optional parameters like width, height, and guidance scale to generate images. The response is typically PNG bytes streamed directly, though some deployments return an image_url instead.

• Endpoint: POST /v1/generate/image
• Headers: X-API-Key, Content-Type: application/json
• Body parameters:
  • prompt (string, required) — What to draw.
  • width (int, optional) — Default 1024 or service default.
  • height (int, optional) — Default 1024 or service default.
  • num_steps (int, optional) — Inference steps.
  • guidance (float, optional) — Classifier-free guidance scale.
  • seed (int, optional)
  • strength (float, optional) — For img2img style strength if supported.

cURL

curl -X POST https://zynapse.zkagi.ai/v1/generate/image \
  -H "X-API-Key: <YOUR_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a man wearing ZKAGI texted tshirt and eating burger",
    "width": 720,
    "height": 1024,
    "num_steps": 24,
    "guidance": 3.5,
    "seed": 1,
    "strength": 1
  }' \
  --output image_v1.png

Node.js (fetch)

const res = await fetch("https://zynapse.zkagi.ai/v1/generate/image", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ZYNAPSE_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ prompt: "a man wearing ZKAGI texted tshirt and eating burger", width: 720, height: 1024, num_steps: 24, guidance: 3.5, seed: 1, strength: 1 })
});
const arrayBuffer = await res.arrayBuffer();
fs.writeFileSync("image_v1.png", Buffer.from(arrayBuffer));

Python

import requests
payload = {
  "prompt": "a man wearing ZKAGI texted tshirt and eating burger",
  "width": 720,
  "height": 1024,
  "num_steps": 24,
  "guidance": 3.5,
  "seed": 1,
  "strength": 1
}
r = requests.post('https://zynapse.zkagi.ai/v1/generate/image', headers={'X-API-Key': 'YOUR_KEY','Content-Type':'application/json'}, json=payload)
open('image_v1.png','wb').write(r.content)

Response: PNG bytes (image stream). Some deployments may return { "image_url": "..." } instead.

---

How do I generate videos with the Zynapse API?

Send a JSON POST request to /v1/generate-video with a text prompt and optional tuning parameters like frame count and aspect ratio. The API returns a job object with a status and download URL, or in some deployments streams the video file directly.

• Endpoint: POST /v1/generate-video
• Headers: X-API-Key, Content-Type: application/json
• Body parameters:
  • prompt (string, required)
  • fast_mode (string, optional) — e.g., Fast | Balanced | Quality
  • lora_scale (number, optional)
  • num_frames (int, optional) — e.g., 81
  • aspect_ratio (string, optional) — e.g., 16:9
  • sample_shift, sample_steps, frames_per_second, sample_guide_scale (optional tuning params)

cURL

curl -X POST 'https://zynapse.zkagi.ai/v1/generate-video' \
  -H 'X-API-Key: <YOUR_KEY>' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "A futuristic cityscape at night with flying cars",
    "fast_mode": "Balanced",
    "lora_scale": 1,
    "num_frames": 81,
    "aspect_ratio": "16:9",
    "sample_shift": 5,
    "sample_steps": 30,
    "frames_per_second": 16,
    "sample_guide_scale": 5
  }' \
  -o video_job.json

Node.js (fetch)

const job = await fetch("https://zynapse.zkagi.ai/v1/generate-video", {
  method: "POST",
  headers: { "X-API-Key": process.env.ZYNAPSE_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ prompt: "A futuristic cityscape at night with flying cars", num_frames: 81, aspect_ratio: "16:9" })
}).then(r => r.json());
// If the API is async, poll job.status or download URL in the response

Python

import requests
payload = {
  "prompt": "A futuristic cityscape at night with flying cars",
  "fast_mode": "Balanced",
  "num_frames": 81,
  "aspect_ratio": "16:9"
}
job = requests.post('https://zynapse.zkagi.ai/v1/generate-video', headers={'X-API-Key': 'YOUR_KEY','Content-Type':'application/json'}, json=payload).json()
print(job)

Response (example)

{
  "job_id": "vid_12345",
  "status": "queued",
  "eta_seconds": 90,
  "download_url": null
}

Some deployments return the file directly. If you get binary bytes, write to .mp4.

---

How do I manage users and API keys in Zynapse?

Zynapse provides admin endpoints for adding users, generating API keys with scoped permissions, and revoking keys. These management endpoints are proxied under the same base domain and may require an admin secret or service token.

• Add User: POST /add-user
• Generate API Key: POST /generate-api-key
• Delete API Key: POST /delete-api-key
• Admin endpoints may require an admin secret or service token — check your Zynapse deployment configuration.

Add User

Node.js route example

app.post('/add-user', async (req, res) => {
  const apiUrl = 'https://zynapse.zkagi.ai/add-user';
  await fetchData(apiUrl, res, 'POST', req.body);
});

Generate API Key

Endpoint: POST /generate-api-key

Body (JSON) (example)

{
  "email": "[email protected]",
  "scopes": ["image:write", "kb:read"],
  "ttl_days": 30
}

Node.js route example

app.post('/generate-api-key', async (req, res) => {
  const apiUrl = 'https://zynapse.zkagi.ai/generate-api-key';
  await fetchData(apiUrl, res, 'POST', req.body);
});

Delete API Key

Endpoint: POST /delete-api-key

Body (JSON) (example)

{
  "email": "[email protected]",
  "api_key": "<KEY_TO_REVOKE>"
}

Node.js route example

app.post('/delete-api-key', async (req, res) => {
  const apiUrl = 'https://zynapse.zkagi.ai/delete-api-key';
  await fetchData(apiUrl, res, 'POST', req.body);
});

---

What errors can the Zynapse API return?

The Zynapse API returns errors in a standard JSON envelope with a code, message, and optional details field. Common HTTP status codes range from 400 for bad requests to 503 for service errors.

Standard JSON error envelope (example):

{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "proof_file is required",
    "details": null
  }
}

Common HTTP statuses:

• 400 Bad Request — Missing/invalid parameters
• 401 Unauthorized — Missing or invalid X-API-Key
• 403 Forbidden — Not enough permissions for the resource
• 404 Not Found — Wrong path or resource missing
• 413 Payload Too Large — File exceeds allowed size
• 429 Too Many Requests — Rate limit exceeded
• 500/502/503 — Service error; retry with backoff

---

What are the rate limits and best practices for the Zynapse API?

Zynapse enforces rate limits and returns HTTP 429 when exceeded. Follow best practices like caching proofs client-side, splitting large PDFs, and using exponential backoff to maximize reliability.

• Prefer smaller files; split large PDFs by chapters if possible.
• Cache proofs client-side and reuse with /v1/ask to reduce latency.
• Use exponential backoff for 429/5xx responses.
• Store doc_hash and proof metadata to prevent duplicate uploads.

---

Quick Reference

Feature	Method	Path	Auth	Content-Type
Ask with proof	POST	/v1/ask	X-API-Key	multipart/form-data
Generate proof	POST	/v1/generate_proof	X-API-Key	multipart/form-data
Generate image	POST	/v1/generate/image	X-API-Key	application/json
Generate video	POST	/v1/generate-video	X-API-Key	application/json
Generate API key (admin)	POST	/generate-api-key	Admin token	application/json
Delete API key (admin)	POST	/delete-api-key	Admin token	application/json

---

Related Questions

• How do I authenticate with ZkTerminal?
• How do I get started with ZkTerminal?
• How do I connect my GPU to the ZkAGI cluster?
• How does ZkAGI integrate with the Solana Agent Kit?