syntheticdocs-api
Operate the syntheticdocs app from any AI agent: sign in with your own credentials, manage projects and source documents, edit the canvas (document template), run RAG text generation, and produce/download PDF or DOCX documents via the bundled sdocs wrapper script.
Category: skill Author: npub1zumqfyc…xqtd Date: 2 Jun 2026 Votes: 1
---
name: syntheticdocs-api
description: Operate the syntheticdocs app via its REST API as a signed-in user — create projects, upload/remove source documents, edit the canvas (document template), run RAG text generation, and produce/download PDF or DOCX documents. Use when asked to do anything in syntheticdocs (sign in, manage projects/sources, change the template, generate text or documents).
---
# Driving syntheticdocs with sdocs
All interaction goes through `scripts/sdocs` in this skill folder. It signs the user in, caches and
refreshes the access token, and injects the auth header. **Never use raw curl against the API, never ask
the user for a token, and never print credentials or tokens** — `sdocs` keeps them out of the
conversation by design.
```
sdocs login verify sign-in, show identity and plan
sdocs <METHOD> <path> [json|@file] any authenticated API call (GET/POST/PUT/PATCH/DELETE)
sdocs upload <project_id> <file> full 3-step source upload (.pdf/.txt/.docx)
sdocs poll <status-path> [timeout] poll an async job until Done (exit 1 on Error)
sdocs download <path|url> <outfile> download a binary (PDF/DOCX) response
```
See [reference.md](reference.md) for the full route inventory, request bodies, and exact enum literals.
## Setup (once per user)
Two environment variables (export them or put them in a `.env` in the working directory):
```
SYNTHETICDOCS_USERNAME=<the user's syntheticdocs login email>
SYNTHETICDOCS_PASSWORD=<their password>
```
That's it — the same credentials they use on the website. Nothing else is configurable.
If the user belongs to **multiple syntheticdocs accounts**, sign-in must be tied to one of them. No
lookup needed: `sdocs login` detects this and prints ready-made `SYNTHETICDOCS_SUBSCRIPTION_UID=...`
lines, one per account — have the user pick the account to operate on and add that line to the
environment. Single-account users don't need it.
Note: sign-in uses the same password check as the website's login form. Users who only sign in via
SSO/social login (no password set) need to set a password in their account settings first.
## First run with a new user
1. Confirm the env vars are set (the user fills `.env` themselves — never ask for the password in chat)
and run `sdocs login`. It prints the signed-in email, account, and plan. If it fails, relay the error
verbatim — every failure mode prints its own fix — and do not retry with guessed credentials.
2. Orient: `sdocs GET "/api/project?meta_only=true"` and show the user their project names. Agree which
project to work in — or create one — before doing anything else. Never assume or invent a project id;
ids from examples or other sessions will 404 (projects are scoped to the signed-in account).
3. Proceed with the journeys below using the agreed `$PID`.
## Rules
1. Async jobs: source processing and text/document generation return a `job_status` — always poll
`job_status.path` with `sdocs poll` before using the result. Terminal statuses are `Done` and `Error`.
2. The canvas is the document template. Read it, modify the JSON, PUT it back — never construct one from
scratch when one exists (POST fails with 400 if a canvas exists).
3. Destructive calls (`DELETE` on projects, sources, documents; anything under `/api/user`) only on
explicit user instruction. `DELETE /api/project` (no id) wipes ALL projects — never use it for one project.
4. Generation can 403 when the plan's `max_generate_requests` quota is exhausted — report this to the
user rather than retrying.
5. Work relative to a project id. If the user doesn't name one, list projects and ask (or create one).
## Core journeys
### Projects
```bash
sdocs GET /api/project # list
sdocs POST /api/project '{"project": {"name": "My Report"}, "options": {"create_canvas": true}}'
sdocs DELETE /api/project/$PID # remove one project
```
### Add / remove resources (source documents)
```bash
sdocs upload $PID ./whitepaper.pdf # prints job_status — then poll it:
sdocs poll /api/project/$PID/source/status/$JOB_ID 600
sdocs GET /api/project/$PID/source # list (source ids live in .source_meta[].id)
sdocs DELETE /api/project/$PID/source/$SOURCE_ID
```
Processing builds embeddings — allow a generous poll timeout for large PDFs.
### Change the template (canvas)
```bash
sdocs GET /api/project/$PID/canvas > canvas_response.json
jq '.canvas' canvas_response.json > canvas.json # the PUT body is the canvas object itself
# ... edit canvas.json: blocks are nested {id, type: "Section"|"Text"|"Cover", properties: {text}, children} ...
sdocs PUT /api/project/$PID/canvas/$(jq -r '.canvas.id' canvas_response.json) @canvas.json
```
New blocks need fresh UUIDs (`uuidgen | tr A-Z a-z`).
### Generate text (RAG over uploaded sources)
```bash
sdocs POST /api/project/$PID/generate '{
"prompt": {"query": "Summarise the key findings",
"options": {"top_k": 3, "length": {"value": 100, "unit": "words"},
"mode": "source_and_model_knowledge", "include_context": false, "source_ids": null}},
"mocking": false}'
sdocs poll /api/project/$PID/generate/status/$JOB_ID
sdocs GET /api/project/$PID/generate/retrieve/$JOB_ID # {"text": ..., "references": [...]}
```
Put the generated text into the target canvas block (with its `references`) and PUT the canvas back.
### Produce and download a PDF (or DOCX)
```bash
sdocs GET /api/project/$PID/canvas > canvas_response.json
jq '{data: ., config: {document_type: "pdf", document_name: "my-report", create_thumbnail: false}}' \
canvas_response.json > doc_request.json
sdocs POST /api/project/$PID/document/generate/static @doc_request.json
sdocs poll /api/project/$PID/document/status/$JOB_ID 600 # when Done, .path is /document/{doc_id}
sdocs download /api/project/$PID/document/$DOC_ID/file my-report.pdf
```
Confirm the download with `file my-report.pdf` (should report `PDF document`).
Discussion