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

Authentication

All endpoints (unless explicitly noted) require an API key via header:

X-API-Key: <your_api_key>

Keep keys secret. Rotate and revoke keys using the Admin endpoints below.

Content Types

File upload: multipart/form-data
JSON: application/json
Downloads: binary stream unless otherwise specified

1) Knowledgebase Ask with Proof

Q&A over your document set with a provided proof JSON.

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
}

2) Generate Proof for a File

Uploads a document and returns a proof artifact you can pass to /v1/ask.

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": "..." } ]
}

3) Generate Image

Text‑to‑image rendering.

Endpoint: POST /v1/generate/image

Headers: X-API-Key, Content-Type: application/json

Body

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.

4) Generate Video

Text‑to‑video rendering.

Endpoint: POST /v1/generate-video

Headers: X-API-Key, Content-Type: application/json

Body

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.

5) Admin — Users & API Keys

These management endpoints are proxied under the same base domain.

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);
});

5.2 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);
});

5.3 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);
});

Note: Admin endpoints may also require an admin secret or service token. Check your Zynapse deployment configuration.

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

Rate Limiting & Best Practices

Prefer smaller files, split large PDFs by chapters if possible.
Cache proofs client‑side and reuse with /v1/ask to reduce latency.
Exponential backoff for 429/5xx.
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`

Authentication​

Content Types​

1) Knowledgebase Ask with Proof​

2) Generate Proof for a File​

3) Generate Image​

4) Generate Video​

5) Admin — Users & API Keys​

5.2 Generate API Key​

5.3 Delete API Key​

Errors​

Rate Limiting & Best Practices​

Quick Reference​

Authentication

Content Types

1) Knowledgebase Ask with Proof

2) Generate Proof for a File

3) Generate Image

4) Generate Video

5) Admin — Users & API Keys

5.2 Generate API Key

5.3 Delete API Key

Errors

Rate Limiting & Best Practices

Quick Reference