snapwonders-com Status API

openapi: 3.2.0
info:
  title: snapWONDERS API / MCP Status 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: Status
  description: Service health endpoint. No authentication required.
paths:
  /api/status:
    get:
      tags:
      - Status
      summary: Service health status
      operationId: get_api_status
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                properties:
                  status:
                    description: All internal checks passed
                    type: string
                    enum:
                    - UP
                    example: UP
                  service:
                    type: string
                    example: vaultify
                  version:
                    type: string
                    example: 1.0.0
                  timestamp:
                    type: string
                    format: date-time
                type: object
        '503':
          description: Service unavailable — DOWN (internal fault), MAINTENANCE (scheduled downtime) or DRAINING (this server is being taken out of the pool; the response then omits `service`)
          content:
            application/json:
              schema:
                properties:
                  status:
                    description: DOWN when an internal check fails; MAINTENANCE when the lock file is present; DRAINING when the answering server is being drained for a reboot
                    type: string
                    enum:
                    - DOWN
                    - MAINTENANCE
                    - DRAINING
                    example: MAINTENANCE
                  service:
                    type: string
                    example: vaultify
                  version:
                    type: string
                    example: 1.0.0
                  timestamp:
                    type: string
                    format: date-time
                type: object
      security: []
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