Share

    • syntheticdocs-api

    By zumq…xqtd June 2, 2026

    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 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

    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)

    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)

    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)

    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)

    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).

    Write a comment