snapwonders-com MCP API

openapi: 3.2.0
info:
  title: snapWONDERS API / MCP API
  description: 'The snapWONDERS API is available over **Clearnet**, **Tor** and **I2P** (dark web). All endpoints and this Swagger UI work identically on all three networks. ---


    ## Authentication


    All endpoints **except `GET /api/status`, `OPTIONS /api/tus` and the no-auth MCP methods (`initialize`, `tools/list`, `status`, `*_get_started`)** require an API key, sent in the `X-Api-Key` request header (or as `Authorization: Bearer `):


    ```

    X-Api-Key:

    ```


    Obtain an API key from your **snapWONDERS account profile** once you have a registered account. Keys begin with `sw_` and are hashed server-side — store the raw key immediately after generation as it cannot be retrieved again. ---


    ## SDKs — skip the choreography


    Everything below this section is the **raw HTTP contract**. You do not have to write it yourself. A full run means: create a session → upload each file → start a job → poll until it finishes → fetch the result URLs → download. Uploading is one `POST /api/upload` per file, so the tedious part is the polling and the plumbing rather than the transfer — unless your files are large enough to need the resumable protocol, which is genuinely fiddly. The **snapWONDERS SDKs** collapse all of it into one call. The first two examples do the **same thing** in each language — hide `secret.pdf` inside `cover.jpg` (Vaultify stego) — and the third shows forensic analysis. Each block is self-contained, so it runs as-is. ### Python — hide a file, then download the result


    ```python

    from snapwonders import Client


    client = Client(api_key="sw_...")


    # The last path is the cover; everything before it is a secret. job = client.stego.hide(["secret.pdf", "cover.jpg"], password="Str0ng!Pass")


    for result in job.results():

    result.download("out/")

    ```


    ### JavaScript / TypeScript — the same hide, then download


    ```javascript

    import { Client } from "@snapwonders/sdk";


    const client = new Client("sw_...");


    // The last path is the cover; everything before it is a secret. const job = await client.stego.hide(["secret.pdf", "cover.jpg"], { password: "Str0ng!Pass" });


    for (const result of await job.results()) {

    await result.download("out/");

    }

    ```


    ### Python — forensic analysis, graded A–F


    ```python

    from snapwonders import Client


    client = Client(api_key="sw_...")


    # Grade each file A–F and collect the overlays the analysis produced. job = client.analyse.run(["photo.jpg"], face_detection=True)


    for item in job.results():

    print(item.filename, item.grade, item.face_count)

    for asset in item.assets: # ELA map, face overlay, …

    asset.download("out/")

    ```


    In JavaScript that is the same call — `await client.analyse.run(["photo.jpg"], { face_detection: true })` — with the result fields in camelCase (`item.faceCount`). Sessions, TUS chunking and resume, polling until the job finishes, retries on transient failures, and typed errors are all handled for you. `client.convert` (media conversion) follows the same shape: one call in, results out. | Language | Package | Install | Source |

    |----------|---------|---------|--------|

    | Python (3.10+) | `snapwonders` | `pip install snapwonders` | GitHub |

    | JavaScript / TypeScript (Node 18+) | `@snapwonders/sdk` | `npm install @snapwonders/sdk` | GitHub |

    | PHP (8.2+) | `snapwonders/sdk` | `composer require snapwonders/sdk` | GitHub |

    | Go (1.21+) | — | `go get github.com/snapWONDERS/snapWONDERS-SDK-Go` | GitHub |

    | Ruby, Java, C#, … | generated from this spec | see the Developers hub | — |


    **Status:** All four are **live**. Python and JavaScript via `pip install snapwonders` / `npm install @snapwonders/sdk`; PHP via `composer require snapwonders/sdk` on Packagist; Go straight from GitHub with `go get`. All four clients are **open source on GitHub** (Python, JavaScript / TypeScript, PHP, Go). See the **Developers hub** for full quickstarts and the generation recipe for other languages. Prefer the raw API — or working in a language without a client? Everything the SDKs do is documented below; nothing is hidden from you.'
  version: 1.0.0
servers:
- url: https://snapwonders.com
  description: Clearnet / Web
- url: http://swonderstzr43aczpcwdoyc25vwxngyromja7pyb5sf26ap3v535sxqd.onion
  description: Tor / Dark Web
- url: http://6ymp5jqysizmejdwaqiehcsgjoyb4s7sbgssquishk66drujomka.b32.i2p
  description: I2P / Dark Web
security:
- ApiKey: []
tags:
- name: MCP
  description: Model Context Protocol endpoint for AI agent integration. 19 tools across steganography (`vaultify_*`), forensic analysis (`snapwonders_analyse_*`), and media conversion (`snapwonders_convert_*`). `X-Api-Key` required for all tools except `status`, `vaultify_get_started`, and `snapwonders_get_started`.
paths:
  /api/mcp:
    get:
      tags:
      - MCP
      summary: MCP endpoint — GET not supported
      description: The MCP endpoint only accepts POST requests (JSON-RPC 2.0). This route returns HTTP 405 to inform clients that GET is not a valid method for MCP.
      operationId: get_api_mcp_endpoint_get
      responses:
        '405':
          description: Method Not Allowed — use POST for MCP JSON-RPC calls
    post:
      tags:
      - MCP
      summary: MCP Streamable HTTP endpoint
      description: 'JSON-RPC 2.0 endpoint implementing the **Model Context Protocol** (Streamable HTTP, `2025-03-26`).


        **Authentication:** An `X-Api-Key` header is required for all `tools/call` requests except `status`. Protocol-level calls (`initialize`, `tools/list`) do not require authentication.


        **Protocol calls (no auth required):**

        - `initialize` — Negotiate protocol version and discover capabilities

        - `ping` — Connection health check; returns an empty result `{}`

        - `tools/list` — Enumerate available tools and their input schemas

        - `tools/call` with `name: "status"` — Check service health (no auth)

        - `tools/call` with `name: "vaultify_get_started"` — snapWONDERS Vaultify steganography overview with sample result and sign-up guidance (no auth)

        - `tools/call` with `name: "snapwonders_get_started"` — snapWONDERS analyse and convert overview with sample results and sign-up guidance (no auth)


        **Steganography tools (X-Api-Key required):**

        - `vaultify_session_create` — Create a hide or reveal upload session

        - `vaultify_session_files` — List files uploaded to a session

        - `vaultify_job_start` — Submit options and queue a hide/reveal job

        - `vaultify_job_status` — Poll job progress

        - `vaultify_job_results` — Retrieve result file download info


        **Forensic analysis tools (X-Api-Key required):**

        - `snapwonders_analyse_session_create` — Create an analyse upload session

        - `snapwonders_analyse_session_files` — List files uploaded to an analyse session

        - `snapwonders_analyse_job_start` — Submit options and queue an analyse job

        - `snapwonders_analyse_job_status` — Poll analyse job progress

        - `snapwonders_analyse_job_results` — Retrieve per-item forensic grades

        - `snapwonders_analyse_result` — Get clean JSON result summary by job_uid


        **Media conversion tools (X-Api-Key required):**

        - `snapwonders_convert_session_create` — Create a convert upload session

        - `snapwonders_convert_session_files` — List files uploaded to a convert session

        - `snapwonders_convert_job_start` — Submit options and queue a convert job

        - `snapwonders_convert_job_status` — Poll convert job progress

        - `snapwonders_convert_job_results` — Retrieve per-item converted file info


        **Uploading files:** MCP tool calls carry JSON, so file bytes travel over HTTP alongside the MCP session. Use `POST /api/upload` — one request, file as the body, headers `X-Api-Key`, `X-Upload-Uid`, `X-Filename`, `Content-Type`. No base64 metadata, no byte offsets. Its response reports `ready_for_job_start`, so `*_session_files` is not needed as a verification step.

        *

        * **Size limit: 95 MB (99,614,720 bytes) per file.** The exact figure is returned as `max_upload_bytes` by every `*_session_create` tool, so check it rather than assuming. Larger files must use the resumable TUS endpoint (`POST /api/tus`), which applies no per-file size cap at upload time — size is checked when the job is started, against the total-size and file-count limits for the account tier. Sending an oversized file to `/api/upload` returns 413 with `max_bytes` and `tus_endpoint` in the body.


        Notifications (no `id` key in request) return HTTP 202 with an empty body.'
      operationId: post_api_mcp_endpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                jsonrpc:
                  type: string
                  example: '2.0'
                id:
                  description: Omit entirely for notifications
                  type: string
                  example: '1'
                method:
                  type: string
                  enum:
                  - initialize
                  - ping
                  - tools/list
                  - tools/call
                  example: tools/call
                params:
                  description: 'Required for `tools/call`: `{"name":"vaultify_session_create","arguments":{...}}`'
                  type: object
              type: object
      responses:
        '202':
          description: Notification accepted (no `id` in request)
        '200':
          description: JSON-RPC 2.0 response
        '400':
          description: Parse error
  /api/mcp/:
    post:
      operationId: post_api_mcp_endpoint_slash
      responses:
        default:
          description: ''
      tags:
      - MCP
      summary: Post api mcp endpoint slash
      x-summary-source: derived
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      description: 'API key generated on your snapWONDERS account profile page. Required everywhere except `GET /api/status`, `OPTIONS /api/tus` and the no-auth MCP methods. `Authorization: Bearer <key>` is also accepted.'
      name: X-Api-Key
      in: header