snapwonders-com Media Upload - Direct API

openapi: 3.2.0
info:
  title: snapWONDERS API / MCP Media Upload - Direct 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: Media Upload - Direct
  description: '**Start here.** One request per file: `POST /api/upload` with the file as the request body and four plain headers (`X-Api-Key`, `X-Upload-Uid`, `X-Filename`, `Content-Type`). No protocol to implement, no chunking, no offsets — any HTTP client can do it, including one generated from this spec. Single-shot and **not resumable**: a dropped connection means starting the file again.


    **Limit: 95 MB (99,614,720 bytes) per file**, returned as `max_upload_bytes` by every session-create call — read it rather than hard-coding. Larger files must use **Media Upload - TUS Resumable** below; a `413` here names that endpoint in its body.


    This is the method AI agents use over MCP, and the one to reach for in scripts, CI and server-to-server calls. Using an official SDK? It chooses for you.'
paths:
  /api/upload:
    post:
      tags:
      - Media Upload - Direct
      summary: Direct upload — send a whole file in one request
      description: 'Uploads a file into an existing upload session in a single POST, with the file as the raw request body.


        **This is the recommended method for AI agents, scripts and any caller sending a single file under the size limit.** It needs no protocol support: one request, plain headers, no base64 metadata and no byte offsets.


        The alternative is the **resumable** method (`/api/tus`, TUS protocol), which is what the website and mobile apps use. Choose resumable when the file exceeds the size limit below, when the connection is unreliable (mobile, Tor/I2P), or when you need a progress bar.


        **Order of operations:** create a session (`POST /api/analyse/session`, `/api/convert/session`, or `/api/session`) → upload here → start the job. Check `ready_for_job_start` in the response rather than polling the session-files endpoint. A steganography *hide* needs two uploads — the payload (`X-Upload-Step: 1`) and the cover media (`X-Upload-Step: 2`) — so it only reports ready once both have arrived.


        **`Content-Type` must be set.** Without it `curl --data-binary` sends `application/x-www-form-urlencoded` and the body is parsed as form data rather than a file.


        **`Content-Length` is required**; chunked transfer-encoding is refused. Without a declared length a body truncated in transit cannot be distinguished from a complete one, and analysing a truncated file would return results describing a file you never sent.


        **Retries:** send the same `X-Client-Upload-Id` to make a retry safe. If the original succeeded but its response was lost, the retry returns that original result (HTTP 200, `deduplicated: true`) instead of uploading a second copy. Without the header a retry creates a second file.'
      operationId: post_app_upload_direct_api
      parameters:
      - name: X-Api-Key
        in: header
        description: Your API key
        required: true
        schema:
          type: string
      - name: X-Upload-Uid
        in: header
        description: The upload_uid returned by the session-create call
        required: true
        schema:
          type: string
      - name: X-Filename
        in: header
        description: Original filename, e.g. holiday.jpg. Stored for display only — the file type is detected from the bytes.
        required: false
        schema:
          type: string
      - name: X-Upload-Step
        in: header
        description: 1 = primary payload (default), 2 = cover media for a steganography hide
        required: false
        schema:
          type: integer
          default: 1
      - name: X-Client-Upload-Id
        in: header
        description: Idempotency key. Reuse it on a retry so a lost response cannot produce a duplicate file.
        required: false
        schema:
          type: string
      - name: Content-Type
        in: header
        description: Media type of the file, e.g. image/jpeg
        required: true
        schema:
          type: string
      - name: Content-Length
        in: header
        description: Exact byte size of the body. Chunked transfer-encoding is not accepted.
        required: true
        schema:
          type: integer
      requestBody:
        description: The raw file bytes.
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '201':
          description: Uploaded and stored. Returns the file record, the session status, and `ready_for_job_start`.
        '200':
          description: Replay of a previous upload with the same `X-Client-Upload-Id` — `deduplicated` is true and the original file is returned. Nothing was uploaded twice.
        '400':
          description: '`truncated_body` — the bytes received did not match Content-Length, so the file was rejected unprocessed. Also `empty_body`.'
        '401':
          description: 'Not authenticated. `error` names the exact cause: `missing_api_key`, `malformed_api_key`, `invalid_api_key`, or — when the key itself is valid — `account_not_verified` / `account_inactive`.'
        '404':
          description: '`not_found` — What you''re looking for is not here.'
        '409':
          description: '`session_not_accepting_uploads` — the session''s job has already been started.'
        '411':
          description: '`length_required` — Content-Length is missing (chunked transfer-encoding). Send a fixed-length body or use the resumable endpoint.'
        '413':
          description: '`file_too_large` — over the direct-upload limit. The response carries `max_bytes` and `tus_endpoint` so the caller can switch to the resumable method.'
      security:
      - ApiKey: []
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