> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spoofsense.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit a capture (client token)

> Called by the SDK with the `sst_` client token. Multipart only — no URLs, no raw bodies, no threshold overrides. The response is deliberately minimal: the untrusted client never sees scores or the decision. 3 attempts per session; capture-fault errors (413, 422, NONCE_MISMATCH) consume an attempt, server-fault errors refund it.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/verification_sessions/submit
openapi: 3.1.0
info:
  title: SpoofSense API
  version: '1.0'
  description: >-
    Face liveness and deepfake detection. All errors use the envelope `{"error":
    {"code", "message"}}`. Input errors (4xx) are never charged.
servers:
  - url: https://api.spoofsense.ai
security:
  - secretKey: []
tags:
  - name: Detection
    description: >-
      Stateless checks on an image you already have. Authenticate with your
      secret key.
  - name: Verification sessions
    description: >-
      The secure capture flow used by the SDKs and hosted page. Server-side
      calls use the secret key; client-side calls use the session's sst_ token.
  - name: Service
paths:
  /v1/verification_sessions/submit:
    post:
      tags:
        - Verification sessions
      summary: Submit a capture (client token)
      description: >-
        Called by the SDK with the `sst_` client token. Multipart only — no
        URLs, no raw bodies, no threshold overrides. The response is
        deliberately minimal: the untrusted client never sees scores or the
        decision. 3 attempts per session; capture-fault errors (413, 422,
        NONCE_MISMATCH) consume an attempt, server-fault errors refund it.
      operationId: submitCapture
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: The captured selfie frame (JPEG/WebP), from the live camera.
                client_payload:
                  type: string
                  description: >-
                    JSON string, at most 8 KB: {"nonce": "<from session_info>",
                    "platform": "web", "sdk_version": "…", "signals": {…},
                    "integrity_token": "…"}. The nonce is required and must
                    match the session.
      responses:
        '200':
          description: >-
            Capture scored. No decision or scores are returned to the client —
            read the result server-side.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
                    enum:
                      - complete
                  credits_remaining:
                    type: integer
              example:
                id: vs_1f2e3d4c5b6a79880917263544332211
                status: complete
                credits_remaining: 1232
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/InvalidSessionToken'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '409':
          $ref: '#/components/responses/SessionNotPending'
        '410':
          $ref: '#/components/responses/SessionExpired'
        '413':
          $ref: '#/components/responses/ImageTooLarge'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/TooManyAttempts'
        '502':
          $ref: '#/components/responses/Upstream'
      security:
        - sessionToken: []
components:
  responses:
    BadRequest:
      description: BAD_REQUEST · INVALID_THRESHOLD · NONCE_MISMATCH
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: BAD_REQUEST
              message: Provide 'data' (base64) or 'image_url'
    InvalidSessionToken:
      description: INVALID_SESSION_TOKEN — sst_ token missing, wrong, or no longer valid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INVALID_SESSION_TOKEN
              message: Invalid or expired session token
    InsufficientCredits:
      description: INSUFFICIENT_CREDITS — top up in the console
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INSUFFICIENT_CREDITS
              message: Insufficient credits
    SessionNotPending:
      description: SESSION_NOT_PENDING — already completed or failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: SESSION_NOT_PENDING
              message: Verification session already completed or failed
    SessionExpired:
      description: SESSION_EXPIRED — TTL elapsed; create a new session
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: SESSION_EXPIRED
              message: Verification session expired
    ImageTooLarge:
      description: IMAGE_TOO_LARGE — over 10 MB
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: IMAGE_TOO_LARGE
              message: Image too large (max 10 MB)
    Unprocessable:
      description: >-
        INVALID_IMAGE · FACE_NOT_DETECTED · FACE_TOO_SMALL · IMAGE_BACKLIT —
        user-fixable, never charged
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: FACE_NOT_DETECTED
              message: No face found in the image
    TooManyAttempts:
      description: TOO_MANY_ATTEMPTS — 3 capture attempts used; create a new session
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: TOO_MANY_ATTEMPTS
              message: Verification session attempt limit reached
    Upstream:
      description: UPSTREAM_ERROR — inference service unavailable; retry with backoff
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UPSTREAM_ERROR
              message: Inference service unavailable
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      description: >-
        Your secret key (sk_live_…), server-side only. Also accepted as an
        `x-api-key` header.
    sessionToken:
      type: http
      scheme: bearer
      description: >-
        A verification session's single-use client token (sst_…), minted by POST
        /v1/verification_sessions.

````