isGenAI Prompts API

openapi: 3.2.0
info:
  title: isGenAI public checker Prompts API
  version: 1.2.0
  description: 'Importable contract for the public evidence checker, saved-prompt extraction/optional reconstruction, C2PA Content Credentials inspection, the public remote MCP endpoint and the health endpoint. Other endpoints documented on /api are outside this contract. Evidence checks and image quality measurements do not establish human authorship. Saved records can be edited; reconstructed prompts describe a similar result and are not recovered originals. A valid C2PA signature and a trusted signer are reported separately. Response schemas: isgenai.check.v1, isgenai.prompt.v1 and isgenai.c2pa-inspection.v1; the MCP endpoint speaks JSON-RPC 2.0.'
  termsOfService: https://isgenai.com/terms
  contact:
    name: isGenAI
    url: https://isgenai.com/contact
servers:
- url: https://isgenai.com
  description: Public production API
security: []
tags:
- name: Prompts
  description: Read supported saved image prompts or request optional reconstruction when available
paths:
  /v1/prompt:
    post:
      operationId: extractOrReconstructPrompt
      tags:
      - Prompts
      summary: Read saved image prompts or conditionally reconstruct a prompt
      description: Public endpoint; no account or API key required. Set mode=saved_only explicitly for metadata extraction with no model call or reconstruction fallback. The default auto mode can send an image, text or code to a configured model if a saved image prompt is unavailable. Model availability and shared service limits vary; no paid feature, fixed quota or reconstruction availability is promised here. Uploads are sent to isGenAI; this is not browser-local processing. This endpoint returns a prompt directly and does not create a public case or receipt. The /v1/check privacy and public_receipt fields do not apply. Responses may contain private saved text/settings; do not publish them or put them in shared logs. The route may set an HttpOnly session cookie for service-limit handling.
      security: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/MultipartPromptInput'
            encoding:
              file:
                contentType: image/png, image/jpeg, image/webp, image/avif
            examples:
              savedOnlyImage:
                summary: Bind file to image bytes; @picture.png is curl syntax, not the HTTP value
                value:
                  file: (binary image bytes)
                  mode: saved_only
          application/json:
            schema:
              $ref: '#/components/schemas/JsonPromptInput'
            examples:
              savedOnlyUrl:
                value:
                  url: https://isgenai.com/examples/saved-details/with-saved-details.png
                  mode: saved_only
              optionalTextReconstruction:
                summary: May return 503 when reconstruction is unavailable
                value:
                  text: A short synthetic example supplied by the caller.
                  mode: auto
      responses:
        '200':
          description: Saved image prompt, or conditional auto reconstruction. Inspect status; reconstructed is not a recovered original.
          headers:
            Cache-Control:
              schema:
                type: string
                enum:
                - no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptResponse'
              examples:
                savedShape:
                  summary: Illustrative saved-record response; not a measured extraction
                  value:
                    schema: isgenai.prompt.v1
                    status: saved
                    prompt: A demonstration prompt stored in a controlled image record.
                    note: Found in the file. Saved details can be edited.
                reconstructedShape:
                  summary: Illustrative response shape only; reconstruction availability is not promised
                  value:
                    schema: isgenai.prompt.v1
                    status: reconstructed
                    prompt: Create a similar geometric illustration.
                    note: A prompt for a similar result, not the original.
        '400':
          description: Missing/invalid input or mode; invalid JSON/multipart; unsupported image or URL; saved_only with text/code (image_required); empty or overlong text/code (invalid_text). Unexpected request-processing failures return invalid_request. Unsupported images use HTTP 400, not 415.
          headers:
            Cache-Control:
              schema:
                type: string
                enum:
                - no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptError'
        '403':
          description: Cross-site request or disallowed Origin; error.code is invalid_origin. Server/CLI clients do not need an API key.
          headers:
            Cache-Control:
              schema:
                type: string
                enum:
                - no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptError'
        '409':
          description: The downloaded image does not match nonempty expected_sha256; error.code is content_changed.
          headers:
            Cache-Control:
              schema:
                type: string
                enum:
                - no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptError'
        '413':
          description: JSON body exceeds 131,072 bytes, multipart body exceeds 21,037,056 bytes (too_large), or image bytes exceed 20,971,520 (invalid_size). Use byte limits rather than the legacy human-readable MB wording.
          headers:
            Cache-Control:
              schema:
                type: string
                enum:
                - no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptError'
        '422':
          description: saved_only completed without a supported saved prompt. This is absence of a supported record, not proof that the image was not AI-generated. No model fallback occurs.
          headers:
            Cache-Control:
              schema:
                type: string
                enum:
                - no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoSavedPromptError'
              example:
                error:
                  code: no_saved_prompt
                  message: No supported saved prompt was found in this file.
        '429':
          description: Shared concurrency is full (busy), or optional reconstruction service limits are reached (limit_reached). These are not promised account quotas. Retry-After is supplied by the shared upload limiter, but is not guaranteed on every 429. Stop a batch; do not immediately retry in a loop.
          headers:
            Cache-Control:
              schema:
                type: string
                enum:
                - no-store
            Retry-After:
              description: Optional delay in seconds. Present for the shared upload-capacity response; other 429 branches may omit it.
              schema:
                type: integer
                minimum: 1
                example: 5
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/PromptError'
                - $ref: '#/components/schemas/BusyError'
        '502':
          description: Optional reconstruction provider failed or returned an unusable result; error.code is provider_unavailable. Saved-only extraction does not call that provider.
          headers:
            Cache-Control:
              schema:
                type: string
                enum:
                - no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptError'
        '503':
          description: Optional reconstruction is unavailable; error.code is not_configured. This can occur in auto mode after an image has no supported saved prompt or for text/code. Use saved_only for image extraction without a model fallback.
          headers:
            Cache-Control:
              schema:
                type: string
                enum:
                - no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptError'
components:
  schemas:
    NoSavedPromptError:
      type: object
      required:
      - error
      description: Normal saved-only absence result. The endpoint returns an HTTP 422 error envelope, not a successful not_found status. The batch CLI translates this into its own not_found row.
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              const: no_saved_prompt
            message:
              type: string
      additionalProperties: false
    ReconstructedPromptResponse:
      type: object
      required:
      - schema
      - status
      - prompt
      - note
      description: Conditional auto-mode result from a configured model. Describes a similar result, not the original prompt, creator, model, hidden settings or seed. Never returned for saved_only.
      properties:
        schema:
          type: string
          const: isgenai.prompt.v1
        prompt:
          type: string
          minLength: 1
          maxLength: 16000
          description: Nonblank prompt text, at most 16,000 UTF-16 code units; not an AI-origin verdict.
        note:
          type: string
        status:
          type: string
          const: reconstructed
      additionalProperties: false
    MultipartPromptInput:
      type: object
      required:
      - file
      description: Upload one nonempty still image. Only file and mode are read from multipart requests; JSON-only URL/text/code inputs are not multipart alternatives. Full multipart body cap is 21,037,056 bytes including boundaries and fields.
      x-maxBodyBytes: 21037056
      properties:
        file:
          type: string
          format: binary
          minLength: 1
          x-maxSizeBytes: 20971520
          description: Still PNG, JPEG, WebP or AVIF bytes; nonempty, at most 20,971,520 bytes (20 MiB), at most 40,000,000 decoded pixels, one page/frame. Invalid, unsupported or multipage images return HTTP 400 unsupported_image. File bytes are uploaded to isGenAI, not processed only in the browser.
        mode:
          type: string
          enum:
          - auto
          - saved_only
          default: auto
          description: saved_only reads supported saved image records without a model call; no record returns HTTP 422. auto first reads image records, then may reconstruct a prompt when configured and within service limits. Reconstruction availability is not guaranteed.
    JsonPromptInput:
      type: object
      description: 'Send one image URL, text or code field. When several fields are strings, URL takes precedence, then code, then text. kind=code also marks a text-field input as code. JSON body cap: 131,072 bytes (128 KiB). saved_only requires an image URL; text/code require auto. An explicit null mode is treated as omitted/auto.'
      x-maxBodyBytes: 131072
      anyOf:
      - required:
        - url
      - required:
        - text
      - required:
        - code
      properties:
        url:
          type: string
          minLength: 1
          description: Direct public HTTP(S) image URL. The fetched resource must have a successful image response and satisfy the same 20 MiB/still-image limits. Private network targets and unsafe requests are rejected; authentication, paywalls and CAPTCHAs are not bypassed.
        text:
          type: string
          minLength: 1
          maxLength: 16000
          description: Nonblank input, at most 16,000 UTF-16 code units including surrounding whitespace. Some Unicode characters use two units. Text/code support auto reconstruction only; saved_only returns HTTP 400 image_required.
        code:
          type: string
          minLength: 1
          maxLength: 16000
          description: Nonblank input, at most 16,000 UTF-16 code units including surrounding whitespace. Some Unicode characters use two units. Text/code support auto reconstruction only; saved_only returns HTTP 400 image_required.
        kind:
          type: string
          enum:
          - text
          - code
          default: text
          description: Optional text/code hint. A string code field always selects code.
        expected_sha256:
          type: string
          description: Optional exact SHA-256 fingerprint for the downloaded URL image bytes. A nonempty value that does not match produces HTTP 409 content_changed. Applies only to JSON URL input; not read from multipart fields.
        mode:
          type:
          - string
          - 'null'
          enum:
          - auto
          - saved_only
          - null
          default: auto
          description: saved_only reads supported saved image records without a model call; no record returns HTTP 422. auto first reads image records, then may reconstruct a prompt when configured and within service limits. Reconstruction availability is not guaranteed.
    PromptError:
      type: object
      required:
      - error
      description: Prompt-route errors have no top-level schema field. Branch on HTTP status and error.code; error.message is human-readable context.
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
            message:
              type: string
      additionalProperties: false
    BusyError:
      type: object
      description: Shared concurrency limiter response, without a schema field. Current responses include code=busy; code remains optional for compatibility with historical message-only responses.
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: string
              enum:
              - busy
          required:
          - message
      required:
      - error
    PromptResponse:
      oneOf:
      - $ref: '#/components/schemas/SavedPromptResponse'
      - $ref: '#/components/schemas/ReconstructedPromptResponse'
      discriminator:
        propertyName: status
        mapping:
          saved: '#/components/schemas/SavedPromptResponse'
          reconstructed: '#/components/schemas/ReconstructedPromptResponse'
    SavedPromptResponse:
      type: object
      required:
      - schema
      - status
      - prompt
      - note
      description: Supported saved image records were found. No model reconstruction was called. Saved prompts, model labels and settings can be edited and do not authenticate origin. Keep returned content out of shared logs.
      properties:
        schema:
          type: string
          const: isgenai.prompt.v1
        prompt:
          type: string
          minLength: 1
          maxLength: 16000
          description: Nonblank prompt text, at most 16,000 UTF-16 code units; not an AI-origin verdict.
        note:
          type: string
        status:
          type: string
          const: saved
        negative_prompt:
          type: string
        recorded_model:
          type: string
          description: A model label found in the image record, not a verified model attribution.
        settings:
          $ref: '#/components/schemas/SavedPromptSettings'
      additionalProperties: false
    SavedPromptSettings:
      type: object
      additionalProperties: false
      description: Only settings explicitly recovered from supported saved records. Absent values are omitted, not inferred. Seed is a string to preserve integer precision.
      properties:
        seed:
          type: string
          pattern: ^-?\d{1,20}$
        steps:
          type: integer
          minimum: 1
        sampler:
          type: string
          maxLength: 200
        scheduler:
          type: string
          maxLength: 200
        cfg_scale:
          type: number
        width:
          type: integer
          minimum: 1
        height:
          type: integer
          minimum: 1
        denoise:
          type: number
          minimum: 0
          maximum: 1
externalDocs:
  description: API instructions and interpretation
  url: https://isgenai.com/api
x-mcp:
  endpoint: https://isgenai.com/mcp
  transport: streamable-http
  stateless: true
  authentication: none
  tools:
  - check_text
  - check_url
  - check_image
  - extract_saved_prompt
  - read_content_credentials
  serverCard: https://isgenai.com/.well-known/mcp/server-card.json
  documentation: https://isgenai.com/developers/mcp